Alibaba Cloud Model Studio:Reconocimiento de voz no en tiempo real

Los modelos de reconocimiento de voz no en tiempo real convierten audio grabado en texto. Admiten reconocimiento multilingüe, reconocimiento de canto, rechazo de ruido y diarización de hablantes, lo que los hace adecuados para transcripción de reuniones, análisis de llamadas, generación de subtítulos y escenarios similares.

Visión general

Transcriba archivos de audio y video grabados en lotes mediante tareas asíncronas.

• La mejora de contexto aumenta la precisión del reconocimiento mediante un contexto configurable.
• Las palabras clave personalizadas mejoran la precisión de reconocimiento de nombres propios mediante una lista de palabras predefinida.
• Las funciones configurables incluyen diarización de hablantes, filtrado de palabras sensibles y marcas de tiempo a nivel de oración o palabra.
• La transcripción asíncrona admite un solo archivo de audio de hasta 12 horas de duración y hasta 2 GB de tamaño.
• Se admite cualquier frecuencia de muestreo, junto con formatos de audio y video convencionales como AAC, WAV y MP3.

Para escenarios en tiempo real como subtítulos en vivo, reuniones en línea y asistentes de voz, utilice Reconocimiento de voz en tiempo real. Para obtener orientación sobre la selección de modelos, consulte Voz a texto.

Requisitos previos

• Una clave de API está Obtener una clave de API y configurada como variable de entorno.
• Para llamar a la API a través del SDK de DashScope, instale el SDK más reciente.

Inicio rápido

curl -X POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-Async: enable" \
-d '{
    "model": "qwen-audio-3.1-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "channel_id": [0],
        "language_hints": ["zh", "en"]
    }
}'

curl -X GET 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json"

# Replace {transcription_url} with the transcription_url value returned by the query API
curl -sS '{transcription_url}' -o transcription.json
cat transcription.json | jq .

from http import HTTPStatus
from dashscope.audio.asr import Transcription
from urllib import request
import dashscope
import os
import json

# The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

task_response = Transcription.async_call(
    model='qwen-audio-3.1-asr-flash-filetrans',
    file_urls=['{YOUR_AUDIO_URL}'],
    language_hints=['zh', 'en']  # language_hints is an optional parameter used to specify the language codes of the audio to be recognized. For the value range, see the API reference documentation.
)

transcription_response = Transcription.wait(task=task_response.output.task_id)

if transcription_response.status_code == HTTPStatus.OK:
    for transcription in transcription_response.output['results']:
        if transcription['subtask_status'] == 'SUCCEEDED':
            url = transcription['transcription_url']
            result = json.loads(request.urlopen(url).read().decode('utf8'))
            print(json.dumps(result, indent=4,
                            ensure_ascii=False))
        else:
            print('transcription failed!')
            print(transcription)
else:
    print('Error: ', transcription_response.output.message)

import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.*;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Arrays;
import java.util.List;

public class Main {
    public static void main(String[] args) {
        // The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        // Create the transcription request parameters.
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
                        // If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: .apiKey("sk-xxx")
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .model("qwen-audio-3.1-asr-flash-filetrans")
                        // language_hints is an optional parameter used to specify the language codes of the audio to be recognized. For the value range, see the API reference documentation.
                        .parameter("language_hints", new String[]{"zh", "en"})
                        .fileUrls(
                                Arrays.asList(
                                        "{YOUR_AUDIO_URL}"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // Submit the transcription request
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // Check whether the task was submitted successfully
            if (result.getTaskId() == null) {
                System.out.println("Error: " + result.getOutput());
                System.exit(1);
            }
            // Block and wait for the task to complete and get the result
            result = transcription.wait(
                    TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
            // Get the transcription result
            List<TranscriptionTaskResult> taskResultList = result.getResults();
            if (taskResultList != null && taskResultList.size() > 0) {
                for (TranscriptionTaskResult taskResult : taskResultList) {
                    String transcriptionUrl = taskResult.getTranscriptionUrl();
                    HttpURLConnection connection =
                            (HttpURLConnection) new URL(transcriptionUrl).openConnection();
                    connection.setRequestMethod("GET");
                    connection.connect();
                    BufferedReader reader =
                            new BufferedReader(new InputStreamReader(connection.getInputStream()));
                    Gson gson = new GsonBuilder().setPrettyPrinting().create();
                    JsonElement jsonResult = gson.fromJson(reader, JsonObject.class);
                    System.out.println(gson.toJson(jsonResult));
                }
            }
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

{
    "file_url": "{YOUR_AUDIO_URL}",
    "properties": {
        "audio_format": "pcm_s16le",
        "channels": [
            0
        ],
        "original_sampling_rate": 16000,
        "original_duration_in_milliseconds": 3834
    },
    "transcripts": [
        {
            "channel_id": 0,
            "content_duration_in_milliseconds": 2480,
            "text": "Hello World, this is the Alibaba Speech Lab.",
            "sentences": [
                {
                    "begin_time": 760,
                    "end_time": 3240,
                    "text": "Hello World, this is the Alibaba Speech Lab.",
                    "sentence_id": 1,
                    "words": [
                        {
                            "begin_time": 760,
                            "end_time": 1000,
                            "text": "Hello",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 1000,
                            "end_time": 1120,
                            "text": " World",
                            "punctuation": ","
                        },
                        {
                            "begin_time": 1400,
                            "end_time": 1920,
                            "text": "this is",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 1920,
                            "end_time": 2520,
                            "text": "the Alibaba",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 2520,
                            "end_time": 2840,
                            "text": "Speech",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 2840,
                            "end_time": 3240,
                            "text": "Lab",
                            "punctuation": "."
                        }
                    ]
                }
            ]
        }
    ]
}

curl --location --request POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-SSE: disable" \
     --data '{
    "model": "qwen-audio-3.1-asr-flash",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "{YOUR_AUDIO_URL}"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000"
    }
}'

{
  "output": {
    "output": {
      "sentence": {
        "text": "Recognized text content"
      }
    },
    "text": "Hello World, this is the Alibaba Speech Lab."
  },
  "request_id": "..."
}

Funciones avanzadas

Usar la API compatible con OpenAI

Solo las series de modelos Qwen3-ASR-Flash admiten llamadas a través del modo compatible con OpenAI. Este modo acepta únicamente URL de archivos de audio accesibles públicamente. No acepta la ruta absoluta de un archivo de audio local.

Use el SDK de Python de OpenAI 1.52.0 o posterior, o el SDK de Node.js 4.68.0 o posterior. Para instalar o actualizar el SDK, ejecute:

# Python
pip install -U "openai>=1.52.0"

# Node.js
npm install openai@^4.68.0

asr_options no es un parámetro estándar de OpenAI. Con el SDK de Python de OpenAI, páselo a través de extra_body. Con el SDK de Node.js de OpenAI, pase asr_options directamente como un parámetro de nivel superior en el cuerpo de la solicitud.

from openai import OpenAI
import os

try:
    client = OpenAI(
        # The API Key differs between the Singapore/US regions and the Beijing region. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
        # If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key = "sk-xxx",
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
        base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
    )

    stream_enabled = False  # Whether to enable streaming output
    completion = client.chat.completions.create(
        model="qwen3-asr-flash",
        messages=[
            {
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "{YOUR_AUDIO_URL}"
                        }
                    }
                ],
                "role": "user"
            }
        ],
        stream=stream_enabled,
        # When stream is set to False, the stream_options parameter cannot be set
        # stream_options={"include_usage": True},
        extra_body={
            "asr_options": {
                # "language": "zh",
                "enable_itn": False
            }
        }
    )
    if stream_enabled:
        full_content = ""
        print("The streaming output is:")
        for chunk in completion:
            # If stream_options.include_usage is True, the choices field of the last chunk is an empty list and needs to be skipped (you can get the Token usage via chunk.usage)
            print(chunk)
            if chunk.choices and chunk.choices[0].delta.content:
                full_content += chunk.choices[0].delta.content
        print(f"The complete content is: {full_content}")
    else:
        print(f"The non-streaming output is: {completion.choices[0].message.content}")
except Exception as e:
    print(f"Error message: {e}")

// Preparations before running:
// Common to Windows/Mac/Linux:
// 1. Make sure Node.js is installed (version >= 14 recommended)
// 2. Run the following command to install the required dependencies: npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  // The API Key differs between the Singapore/US regions and the Beijing region. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
  // If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: apiKey: "sk-xxx",
  apiKey: process.env.DASHSCOPE_API_KEY,
  // The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
  baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});

async function main() {
  try {
    const streamEnabled = false; // Whether to enable streaming output
    const completion = await client.chat.completions.create({
      model: "qwen3-asr-flash",
      messages: [
        {
          role: "user",
          content: [
            {
              type: "input_audio",
              input_audio: {
                data: "{YOUR_AUDIO_URL}"
              }
            }
          ]
        }
      ],
      stream: streamEnabled,
      // When stream is set to False, the stream_options parameter cannot be set
      // stream_options: {
      //   "include_usage": true
      // },
      asr_options: {
        // language: "zh",
        enable_itn: false
      }
    });

    if (streamEnabled) {
      let fullContent = "";
      console.log("The streaming output is:");
      for await (const chunk of completion) {
        console.log(JSON.stringify(chunk));
        if (chunk.choices && chunk.choices.length > 0) {
          const delta = chunk.choices[0].delta;
          if (delta && delta.content) {
            fullContent += delta.content;
          }
        }
      }
      console.log(`The complete content is: ${fullContent}`);
    } else {
      console.log(`The non-streaming output is: ${completion.choices[0].message.content}`);
    }
  } catch (err) {
    console.error(`Error message: ${err}`);
  }
}

main();

curl -X POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3-asr-flash",
    "messages": [
        {
            "content": [
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": "{YOUR_AUDIO_URL}"
                    }
                }
            ],
            "role": "user"
        }
    ],
    "stream":false,
    "asr_options": {
        "enable_itn": false
    }
}'

import base64
from openai import OpenAI
import os
import pathlib

try:
    # Replace with the actual audio file path
    file_path = "{YOUR_AUDIO_FILE}"
    # Replace with the actual MIME type of the audio file
    audio_mime_type = "audio/mpeg"

    file_path_obj = pathlib.Path(file_path)
    if not file_path_obj.exists():
        raise FileNotFoundError(f"Audio file does not exist: {file_path}")

    base64_str = base64.b64encode(file_path_obj.read_bytes()).decode()
    data_uri = f"data:{audio_mime_type};base64,{base64_str}"

    client = OpenAI(
        # The API Key differs between the Singapore/US regions and the Beijing region. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
        # If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key = "sk-xxx",
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
        base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
    )

    stream_enabled = False  # Whether to enable streaming output
    completion = client.chat.completions.create(
        model="qwen3-asr-flash",
        messages=[
            {
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": data_uri
                        }
                    }
                ],
                "role": "user"
            }
        ],
        stream=stream_enabled,
        # When stream is set to False, the stream_options parameter cannot be set
        # stream_options={"include_usage": True},
        extra_body={
            "asr_options": {
                # "language": "zh",
                "enable_itn": False
            }
        }
    )
    if stream_enabled:
        full_content = ""
        print("The streaming output is:")
        for chunk in completion:
            # If stream_options.include_usage is True, the choices field of the last chunk is an empty list and needs to be skipped (you can get the Token usage via chunk.usage)
            print(chunk)
            if chunk.choices and chunk.choices[0].delta.content:
                full_content += chunk.choices[0].delta.content
        print(f"The complete content is: {full_content}")
    else:
        print(f"The non-streaming output is: {completion.choices[0].message.content}")
except Exception as e:
    print(f"Error message: {e}")

// Preparations before running:
// Common to Windows/Mac/Linux:
// 1. Make sure Node.js is installed (version >= 14 recommended)
// 2. Run the following command to install the required dependencies: npm install openai

import OpenAI from "openai";
import { readFileSync } from 'fs';

const client = new OpenAI({
  // The API Key differs between the Singapore/US regions and the Beijing region. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
  // If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: apiKey: "sk-xxx",
  apiKey: process.env.DASHSCOPE_API_KEY,
  // The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
  baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});

const encodeAudioFile = (audioFilePath) => {
    const audioFile = readFileSync(audioFilePath);
    return audioFile.toString('base64');
};

// Replace with the actual audio file path
const dataUri = `data:audio/mpeg;base64,${encodeAudioFile("{YOUR_AUDIO_FILE}")}`;

async function main() {
  try {
    const streamEnabled = false; // Whether to enable streaming output
    const completion = await client.chat.completions.create({
      model: "qwen3-asr-flash",
      messages: [
        {
          role: "user",
          content: [
            {
              type: "input_audio",
              input_audio: {
                data: dataUri
              }
            }
          ]
        }
      ],
      stream: streamEnabled,
      // When stream is set to False, the stream_options parameter cannot be set
      // stream_options: {
      //   "include_usage": true
      // },
      asr_options: {
        // language: "zh",
        enable_itn: false
      }
    });

    if (streamEnabled) {
      let fullContent = "";
      console.log("The streaming output is:");
      for await (const chunk of completion) {
        console.log(JSON.stringify(chunk));
        if (chunk.choices && chunk.choices.length > 0) {
          const delta = chunk.choices[0].delta;
          if (delta && delta.content) {
            fullContent += delta.content;
          }
        }
      }
      console.log(`The complete content is: ${fullContent}`);
    } else {
      console.log(`The non-streaming output is: ${completion.choices[0].message.content}`);
    }
  } catch (err) {
    console.error(`Error message: ${err}`);
  }
}

main();

Procesar archivos de audio largos

El reconocimiento de voz no en tiempo real admite la transcripción asíncrona de archivos de audio largos. Esto es adecuado para escenarios como minutas de reuniones, transcripciones de entrevistas y reproducción de llamadas.

• Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR / Qwen3-ASR-Flash-Filetrans / Paraformer: un solo archivo de audio puede tener hasta 2 GB de tamaño y 12 horas de duración.
• Qwen-Audio-3.1-ASR-Flash: un solo archivo de audio puede tener hasta 2 GB de tamaño y 5 minutos de duración.
• Qwen-Audio-3.0-ASR-Flash/Fun-ASR-Flash/Qwen3-ASR-Flash: un solo archivo de audio puede tener hasta 10 MB de tamaño y 5 minutos de duración. Para audios más largos, utilice Qwen-Audio-3.1-ASR-Flash-Filetrans, Fun-ASR o Qwen3-ASR-Flash-Filetrans.
• Cuando la diarización de hablantes está habilitada: mantenga la duración del audio dentro de 2 horas. Un audio más largo puede provocar fallos en el reconocimiento o tiempos de espera agotados. Para obtener más información, consulte Diarización de hablantes.

Flujo de llamada: la transcripción de audio largo utiliza un modelo de tarea asíncrona con tres pasos:

1. Envíe la tarea de transcripción y obtenga un task_id.
2. Sondee la API de consulta para obtener el estado de la tarea o use el método de espera del SDK para bloquear hasta que la tarea se complete.
3. Una vez completada la tarea, descargue el JSON del resultado de reconocimiento desde la URL devuelta.

Para ver código de ejemplo, consulte el código de Inicio rápido en Reconocimiento de voz no en tiempo real.

Salida por secuencias

Qwen-Audio-3.1-ASR-Flash admite resultados de reconocimiento por streaming mediante HTTP SSE. Para conocer el formato de solicitud y respuesta, consulte API HTTP.

Qwen-Audio-3.0-ASR-Flash/Fun-ASR-Flash/Qwen3-ASR-Flash admiten salida por streaming: devuelven resultados intermedios a medida que avanza el reconocimiento. Esto es adecuado para escenarios que requieren retroalimentación de progreso en tiempo real.

Los modelos de transcripción asíncrona como Qwen-Audio-3.x-ASR-Flash-Filetrans, Fun-ASR, Qwen3-ASR-Flash-Filetrans y Paraformer no admiten salida en streaming. Obtenga el resultado final mediante el sondeo de la tarea (para más información, consulte Procesamiento de archivos de audio largos).

• DashScope Python SDK: establezca el parámetro stream en True.
• DashScope Java SDK: llame a la API streamCall.
• DashScope HTTP: establezca el encabezado X-DashScope-SSE en enable.
• SDK compatible con OpenAI: establezca el parámetro stream en True.

Para ejemplos de salida de transmisión de Qwen3-ASR-Flash, consulte Ejemplos de solicitud y seleccione la pestaña de salida Streaming.

Mejorar la precisión con palabras clave

Las palabras clave mejoran la precisión del reconocimiento de sustantivos propios específicos del dominio, como nombres, topónimos y nombres de productos. Para obtener detalles sobre cómo crear y utilizar palabras clave, consulte Mejorar la precisión del reconocimiento.

Diferentes SDK utilizan distintas convenciones de nomenclatura para estos parámetros, como claves de diccionario, propiedades de objeto o métodos. Para obtener la asignación completa de campos, consulte la referencia de la API de cada SDK.

Mejorar la precisión con la mejora de contexto

La mejora de contexto pasa el historial de conversaciones al modelo ASR, lo que mejora significativamente la precisión de la transcripción de sustantivos propios. Para obtener detalles sobre cómo utilizar esta función y ver ejemplos de resultados, consulte Mejora de contexto.

Diarización de hablantes

Qwen-Audio-3.1-ASR-Flash habilita la diarización de hablantes con speaker_diarization_enabled. Para conocer sus parámetros y estructura de respuesta, consulte API HTTP.

La diarización de hablantes identifica automáticamente a los distintos hablantes en el audio y etiqueta cada oración en el resultado de la transcripción con una etiqueta de hablante. Esto es adecuado para escenarios como reuniones multipartitas y grabaciones de entrevistas.

La siguiente configuración y ejemplo se aplican a: las series de modelos Qwen-Audio-3.x-ASR-Flash-Filetrans, Fun-ASR y Paraformer.

Cómo habilitar: establezca el parámetro diarization_enabled en true en la solicitud de API. En el resultado, cada oración incluye un campo speaker_id que identifica al hablante.

Estructura de retorno de ejemplo (extracto):

{
  "transcripts": [
    {
      "sentences": [
        { "begin_time": 100, "end_time": 3820, "text": "Hello, let's discuss the project progress today.", "speaker_id": 0 },
        { "begin_time": 3820, "end_time": 6500, "text": "Sure, let me give a quick report first.", "speaker_id": 1 }
      ]
    }
  ]
}

Diferentes SDK utilizan distintas convenciones de nomenclatura para estos campos, como claves de diccionario, propiedades de objeto o métodos. Para obtener la asignación completa de campos, consulte la referencia de la API de cada SDK.

Para las definiciones completas de los campos, consulte la referencia de la API.

Filtrado de palabras sensibles

El filtrado de palabras sensibles reemplaza o elimina palabras sensibles en el resultado del reconocimiento. Esto es adecuado para escenarios como inspección de calidad de servicio al cliente, cumplimiento de contenido y moderación de subtítulos.

Modelos admitidos: las series de modelos Qwen-Audio-3.x-ASR-Flash-Filetrans, Fun-ASR y Paraformer.

Comportamiento predeterminado: cuando no se pasa el parámetro special_word_filter, el sistema utiliza la lista de palabras sensibles de Model Studio integrada. Las palabras coincidentes se reemplazan por una cadena de igual longitud compuesta por *.

Configuración personalizada: special_word_filter es un objeto JSON con tres subcampos:

• filter_with_signed.word_list: un arreglo de cadenas de palabras sensibles que se reemplazarán por una cadena de igual longitud compuesta por *. Por ejemplo, con ["test"], "Por favor ayúdame a probar esto" se convierte en "Por favor ayúdame a **** esto".
• filter_with_empty.word_list: un arreglo de cadenas de palabras sensibles que se eliminarán por completo del resultado. Por ejemplo, con ["start"], "¿El juego está a punto de comenzar ahora?" se convierte en "¿El juego está a punto de ahora?".
• system_reserved_filter: un valor booleano cuyo valor predeterminado es true. Controla si también se aplica la lista integrada de palabras sensibles del sistema, la cual surte efecto junto con su lista personalizada.

Ejemplo de configuración:

{
  "special_word_filter": {
    "filter_with_signed": {
      "word_list": ["test"]
    },
    "filter_with_empty": {
      "word_list": ["start", "happen"]
    },
    "system_reserved_filter": true
  }
}

Diferentes SDK utilizan distintas convenciones de nomenclatura para estos parámetros, como claves de diccionario, propiedades de objeto o métodos. Para obtener la asignación completa de campos, consulte la referencia de la API.

Reconocimiento de emociones

Los modelos de las series Qwen3-ASR-Flash-Filetrans y Qwen3-ASR-Flash tienen el reconocimiento de emociones habilitado permanentemente, sin necesidad de configuración adicional. El resultado incluye una etiqueta de emoción para el hablante, elegida entre siete emociones detalladas: surprised, neutral, happy, sad, disgusted, angry y fearful.

Rutas de campos (varían según la API):

• API compatible con OpenAI (transcripción en tiempo real de Qwen3-ASR-Flash): anidado en choices[].delta.annotations[].emotion (salida por streaming) o choices[].message.annotations[].emotion (sin streaming).
• API síncrona de DashScope (Qwen3-ASR-Flash): anidado en output.choices[].message.annotations[].emotion.
• API de tareas asíncronas de DashScope (transcripción de archivos de grabación de Qwen3-ASR-Flash-Filetrans): anidado en transcripts[].sentences[].emotion, junto con la marca de tiempo, el hablante y otros campos en cada objeto de oración.

Estructura de retorno de ejemplo (extracto de la API de tareas asíncronas de DashScope):

{
  "transcripts": [{
    "sentences": [{
      "begin_time": 0,
      "end_time": 1440,
      "text": "Welcome to Alibaba Cloud.",
      "emotion": "neutral",
      "language": "en"
    }]
  }]
}

Diferentes SDK utilizan distintas convenciones de nomenclatura para estos campos, como claves de diccionario, propiedades de objeto o métodos. Para obtener la asignación completa de campos, consulte la referencia de la API.

Obtener marcas de tiempo

Para conocer la estabilidad de las marcas de tiempo y las rutas de campos en las respuestas por streaming de Flash, consulte Manejo de respuestas de la API HTTP.

El reconocimiento de voz no en tiempo real puede generar marcas de tiempo en el resultado de la transcripción, lo cual facilita la generación de subtítulos, el resaltado de palabras clave y la edición de audio y video. Qwen-Audio-3.x-ASR-Flash-Filetrans, Qwen-Audio-3.x-ASR-Flash, Fun-ASR, Fun-ASR-Flash, Qwen3-ASR-Flash-Filetrans y Paraformer admiten marcas de tiempo, pero el comportamiento predeterminado y el método de control varían según el modelo:

• Qwen-Audio-3.x-ASR-Flash-Filetrans/Qwen-Audio-3.x-ASR-Flash/Fun-ASR/Fun-ASR-Flash/Paraformer: las marcas de tiempo están habilitadas permanentemente y no se pueden desactivar.
• Qwen3-ASR-Flash-Filetrans: solo la llamada asíncrona de DashScope admite marcas de tiempo, y estas están habilitadas permanentemente. Utilice el parámetro de solicitud enable_words para controlar el nivel de las marcas de tiempo: configúrelo en false (predeterminado) para devolver marcas de tiempo a nivel de oración, o en true para devolver marcas de tiempo a nivel de palabra. Las marcas de tiempo a nivel de palabra solo admiten los siguientes idiomas: chino, inglés, japonés, coreano, alemán, francés, español, italiano, portugués y ruso. No se garantiza la precisión para otros idiomas.

Las marcas de tiempo están en milisegundos y se devuelven en dos niveles:

• Nivel de oración: sentences[].begin_time y sentences[].end_time marcan el tiempo de inicio y fin de cada oración en el audio.
• Nivel de palabra: el arreglo sentences[].words[], donde cada elemento contiene begin_time, end_time y text (el texto de dicha palabra).

Estructura de retorno de ejemplo (extracto de la API de tareas asíncronas de DashScope):

{
  "transcripts": [{
    "sentences": [{
      "begin_time": 100,
      "end_time": 3820,
      "text": "Hello, let's discuss the project progress today.",
      "words": [
        { "begin_time": 100, "end_time": 596, "text": "Hello," },
        { "begin_time": 596, "end_time": 844, "text": "let's" }
      ]
    }]
  }]
}

Diferentes SDK utilizan distintas convenciones de nomenclatura para estos campos, como claves de diccionario, propiedades de objeto o métodos. Para obtener la asignación completa de campos, consulte la referencia de la API.

Aplicar en producción

Cuando aplica el reconocimiento de voz no en tiempo real en producción, las siguientes prácticas recomendadas mejoran la calidad del reconocimiento y la estabilidad del sistema.

Escenarios de alta concurrencia: use devoluciones de llamada en lugar de sondeo

Para tareas de transcripción asíncrona (Qwen-Audio-3.0-ASR-Flash-Filetrans, Fun-ASR, Qwen3-ASR-Flash-Filetrans y Paraformer), usted envía la tarea a través de POST /api/v1/services/audio/asr/transcription y generalmente obtiene el resultado llamando periódicamente a la API de consulta GET /api/v1/tasks/{task_id}. Esta API de consulta tiene un valor predeterminado de 20 QPS y escala hasta 100 QPS. En escenarios por lotes de alta concurrencia, el sondeo frecuente activa fácilmente la limitación de velocidad.

Configure las notificaciones de devolución de llamada a través de EventBridge. Cuando una tarea se completa, Model Studio envía automáticamente un evento dashscope:System:AsyncTaskFinish al destino configurado (un endpoint HTTP/HTTPS o un tema de RocketMQ). Una vez que el consumidor recibe el evento, ya no necesita llamar a la API de consulta, lo que evita el riesgo de limitación por sondeos frecuentes. Para más información, consulte Configuración de notificaciones de devolución de llamada de EventBridge.

Modelos admitidos

• Compatible: Qwen-Audio-3.0-ASR-Flash-Filetrans, Fun-ASR, Qwen3-ASR-Flash-Filetrans y Paraformer (todas las tareas de transcripción asíncrona).
• No admitido: Qwen3-ASR-Flash (llamadas síncronas o en streaming, que no son tareas asíncronas).

Contenido del mensaje de devolución de llamada

Para los tres modelos, el cuerpo del mensaje de devolución de llamada tiene data.contain_result establecido en true, y data.output_result contiene directamente transcription_url. Después de recibir la devolución de llamada, el consumidor puede obtener el resultado de reconocimiento sin necesidad de llamar nuevamente a GET /api/v1/tasks/{task_id}. Sin embargo, la ruta y la estructura del campo de resultado difieren entre los tres modelos. Consulte la siguiente tabla.

Notas de uso

Seguridad (entrega HTTP/HTTPS): en producción, verifique los campos de encabezado X-Eventbridge-Signature* en la solicitud de devolución de llamada antes de consumirla. De lo contrario, cualquier IP externa podría falsificar un evento AsyncTaskFinish e inyectar resultados de reconocimiento falsos. Configure también un tiempo de espera de recepción de al menos 5 segundos en el receptor. El método de entrega de RocketMQ no cuenta con firma a nivel de mensaje; su seguridad está garantizada por el mecanismo de autenticación de RocketMQ.

Latencia de entrega: desde la finalización de la tarea (end_time) hasta que el destino de entrega (un endpoint HTTP/HTTPS o un tema de RocketMQ) recibe el mensaje, el retraso suele ser de aproximadamente 1 a 90 segundos. La latencia exacta depende de la carga en tiempo real de EventBridge.

Idempotencia: el mismo evento puede entregarse varias veces debido a reintentos. Implemente un procesamiento idempotente en el consumidor, utilizando data.id o data.task_id de CloudEvents como clave de deduplicación.

Recomendaciones de producción

• Alojamiento de archivos: cargue los archivos de audio en Alibaba Cloud OSS y llame a la API mediante URL. Evite cargar archivos locales (las llamadas con archivos locales tienen un límite de 100 QPS y no se pueden escalar).
• Sondeo asíncrono: la transcripción de audio largo utiliza un modelo asíncrono. Establezca un intervalo de sondeo razonable (como de 2 a 5 segundos) para evitar consultas frecuentes que consuman su cuota. Para superar el límite de consulta de 20 a 100 QPS, cambie a notificaciones de devolución de llamada por eventos. Para más información, consulte Escenarios de alta concurrencia: uso de devoluciones de llamada en lugar de sondeo.
• Manejo de errores: implemente un mecanismo de reintento robusto. Para tiempos de espera de red o errores temporales del lado del servidor (5xx), reintente con una estrategia de retroceso exponencial.
• Reducción de ruido: para audio con ruido, procéselo previamente con una herramienta como FFmpeg antes de enviarlo para su reconocimiento.
• Selección de modelo: elija el modelo adecuado según la duración del audio. Para audios cortos de menos de 5 minutos, utilice Qwen3-ASR-Flash. Para audios largos de más de 5 minutos, utilice Qwen-Audio-3.1-ASR-Flash-Filetrans, Fun-ASR o Qwen3-ASR-Flash-Filetrans.

Modelos y regiones compatibles

Referencia de API

• Reconocimiento de voz sin tiempo real - Referencia de API de Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR
• Reconocimiento de voz sin tiempo real - Referencia de API de Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash
• Reconocimiento de voz sin tiempo real - Referencia de API de Qwen-ASR
• Reconocimiento de voz sin tiempo real - Referencia de API de Paraformer

FAQ

P: ¿Cómo proporciono una URL de audio accesible públicamente a la API?

Utilice Alibaba Cloud Object Storage Service (OSS). OSS proporciona almacenamiento altamente disponible y confiable, y le permite generar una URL de acceso público.

Verifique que la URL generada sea accesible a través de la red pública: abra la URL en un navegador o con el comando curl para confirmar que el archivo de audio se descarga o reproduce (código de estado HTTP 200).

P: ¿Cómo verifico si el formato de audio cumple con los requisitos?

Use la herramienta de código abierto ffprobe para obtener rápidamente información detallada del audio:

# Query the container format (format_name), codec (codec_name), sample rate (sample_rate), and number of channels (channels) of the audio
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 your_audio_file.mp3

P: ¿Cómo proceso el audio para cumplir con los requisitos del modelo?

Use la herramienta de código abierto FFmpeg para recortar o convertir el audio:

• Recortar audio: extraer un clip de un archivo de audio largo

# -i: input file
# -ss 00:01:30: set the trim start time (start at 1 minute 30 seconds)
# -t 00:02:00: set the trim duration (trim 2 minutes)
# -c copy: copy the audio stream directly without re-encoding, which is fast
# output_clip.wav: output file
ffmpeg -i long_audio.wav -ss 00:01:30 -t 00:02:00 -c copy output_clip.wav

• Convertir el formato

  Por ejemplo, convierta cualquier audio a un archivo WAV mono de 16 kHz y 16 bits:

# -i: input file
# -ac 1: set the number of channels to 1 (mono)
# -ar 16000: set the sample rate to 16000 Hz (16 kHz)
# -sample_fmt s16: set the sample format to 16-bit signed integer PCM
# output.wav: output file
ffmpeg -i input.mp3 -ac 1 -ar 16000 -sample_fmt s16 output.wav

P: ¿Cómo mejoro la precisión del reconocimiento?

Los siguientes factores afectan la precisión del reconocimiento. Revise cada uno y optimice en consecuencia.

Factores principales:

1. Calidad del audio: la calidad del dispositivo de grabación, la frecuencia de muestreo y el ruido ambiental afectan directamente la claridad del audio. Una entrada de audio de alta calidad es la base para un reconocimiento preciso.
2. Características del hablante: el tono, la velocidad del habla, el acento y las diferencias dialectales (especialmente dialectos poco comunes o acentos marcados) aumentan la dificultad del reconocimiento.
3. Idioma y vocabulario: la mezcla de idiomas, los términos técnicos o la jerga aumentan la dificultad del reconocimiento. Configure palabras clave para mejorar la precisión de los términos específicos del dominio.

Métodos de optimización:

1. Mejorar la calidad del audio: use un micrófono de alto rendimiento, grabe a la frecuencia de muestreo recomendada y minimice el ruido ambiental y el eco.
2. Adaptarse al hablante: para audio con acentos marcados o dialectos notorios, elija un modelo que admita el dialecto correspondiente.
3. Configurar palabras clave: defina palabras clave para términos técnicos, nombres propios y palabras similares.