Skip to main content

API HTTP de Qwen-Audio-ASR-Filetrans para reconocimiento de voz no en tiempo real

Este tema describe los parámetros y los detalles de la interfaz de la API HTTP para el reconocimiento de voz no en tiempo real con Qwen-Audio-3.x-ASR-Flash-Filetrans y Qwen-Audio-ASR-Filetrans.

Para los requisitos de entrada, como formatos de audio compatibles, límites de tamaño de archivo y límites de duración, consulte Especificaciones de audio.

Funcionamiento

A diferencia de las llamadas síncronas de DashScope, que devuelven el resultado inmediatamente en una sola solicitud, las llamadas asíncronas están diseñadas para archivos de audio largos o tareas que consumen mucho tiempo. Este modo utiliza un flujo de dos pasos de envío y sondeo que evita los tiempos de espera de solicitud causados por largas esperas:
  1. Paso 1: Enviar la tarea.
    • El cliente envía una solicitud de procesamiento asíncrono.
    • Después de validar la solicitud, el servidor no ejecuta la tarea inmediatamente. En su lugar, devuelve un task_id único para indicar que la tarea se creó correctamente.
  2. Paso 2: Recuperar el resultado.
    • El cliente utiliza el task_id devuelto para sondear repetidamente la interfaz de consulta.
    • Cuando la tarea finaliza, la interfaz de consulta devuelve el resultado final del reconocimiento.

Endpoints de servicio

  • Singapore
  • China (Beijing)
Interfaz de envío de tareas: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcriptionInterfaz de consulta de tareas: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
Alibaba Cloud Model Studio ha lanzado dominios específicos del espacio de trabajo para las regiones China (Pekín) y Singapore. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:
  • China (Pekín): de dashscope.aliyuncs.com a {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapur: de dashscope-intl.aliyuncs.com a {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Encabezados de solicitud

ParámetroTipoObligatorioDescripción
AuthorizationstringSíToken de autenticación en el formato Bearer <your_api_key>. Reemplace "<your_api_key>" con su clave de API real. Requerido tanto para la interfaz de envío de tareas como para la interfaz de consulta de tareas.
Content-TypestringSíEl tipo de medio del cuerpo de la solicitud. Requerido solo para la interfaz de envío de tareas. Valor fijo: application/json.
X-DashScope-AsyncstringSíEl indicador de tarea asíncrona. Requerido solo para la interfaz de envío de tareas. Valor fijo: enable. No lo omita, de lo contrario no se podrá enviar la tarea.

Interfaz de envío de tareas

Envía una tarea de reconocimiento de voz. Esta interfaz responde de forma asíncrona, por lo que debe sondear el estado de la tarea con la Interfaz de consulta de tareas.

Cuerpo de la solicitud

modelstring(Obligatorio)El nombre del modelo.inputobject(Obligatorio)El objeto de parámetros de entrada.

Propiedades

file_urls array[string](Obligatorio)Una lista de URL de los archivos de audio o video a transcribir. Se admiten HTTP y HTTPS. Una sola solicitud admite únicamente una URL. Para los requisitos de entrada, como formatos de audio compatibles, límites de tamaño de archivo y límites de duración, consulte Especificaciones de audio.Si la grabación se almacena en Alibaba Cloud OSS, la API RESTful admite URLs temporales con el prefijo oss://, mientras que el SDK no admite URLs temporales con el prefijo oss://.
  • Una URL temporal es válida durante 48 horas y no se puede usar después de que expire. No la use en producción.
  • La interfaz de credenciales de carga tiene un límite de tasa de 100 QPS y no se puede escalar. No la use en escenarios de producción, alta concurrencia o pruebas de carga.
  • Para producción, utilice almacenamiento estable como Alibaba Cloud OSS para mantener los archivos disponibles a largo plazo y evitar límites de tasa.
  • Si una URL de archivo de audio configurada como una URL pública temporal de OSS no es accesible, configure X-DashScope-OssResourceResolve en enable en el encabezado de la solicitud (no recomendado). El SDK no admite la configuración de encabezados de solicitud.
contextarray(object)(Opcional)Una lista de mensajes que proporcionan contexto de conversación opcional para mejorar la precisión del reconocimiento.
El SDK aún no admite esta función.
La mejora de contexto mejora la precisión del reconocimiento de términos específicos del dominio. Para su uso, consulte Mejora de contexto.Restricciones: Los mensajes de contexto de los tipos input_text y text están limitados a 5 mensajes cada uno. Si supera este límite, solo se conservan los 5 más recientes. La longitud total del texto por turno de contexto (la longitud combinada de los campos text para user y assistant) no debe exceder los 400 caracteres (contados por carácter, cada carácter cuenta como 1). Cualquier exceso se trunca desde el final.
Cuando incluya contexto, el orden de los mensajes en messages es importante: los mensajes de contexto deben organizarse por turno de conversación. Dentro de cada turno, el mensaje user (tipo input_text) debe aparecer antes del mensaje assistant correspondiente (tipo text). Un mensaje user que contenga input_audio debe colocarse al final del arreglo messages.

Propiedades

rolestring(Obligatorio)El rol del mensaje. Valores válidos:
  • user: resultados de reconocimiento de turnos anteriores o una lista de palabras específicas del dominio.
  • assistant: las respuestas del modelo de lenguaje grande de turnos anteriores.
contentarray(object)(Obligatorio)La lista de elementos de contenido del mensaje.

Propiedades

typestring(Obligatorio)El tipo de contenido. Valores válidos:
  • input_text (opcional, contexto): resultados de reconocimiento del habla del usuario de turnos anteriores, o una lista de palabras específicas del dominio (el rol es user). También debe pasar el campo text.
  • text (opcional, contexto): las respuestas del modelo de lenguaje grande de turnos anteriores (el rol es assistant). También debe pasar el campo text.
textstring(Condicionalmente obligatorio)Cuando type es input_text, ingrese los resultados de reconocimiento del habla del usuario de turnos anteriores o una lista de palabras específica del dominio. Cuando type es text, ingrese las respuestas del modelo de lenguaje grande de turnos anteriores. El texto se cuenta por carácter, y cada carácter cuenta como 1. La longitud combinada de los campos text en todos los mensajes de un turno de contexto no debe exceder los 400 caracteres. Cualquier exceso se trunca desde el final.
parametersobject(Obligatorio)Incluya siempre parameters. Si no necesita configurar opciones, pase un objeto vacío {}. Si omite este campo, la tarea de transcripción enviada falla.

Propiedades

keep_dialect boolean (Opcional)Compatible solo con qwen-audio-3.1-asr-flash-filetrans. Especifica si se deben conservar las expresiones dialectales. Valor predeterminado: false. Establezca en false para transcribir el habla dialectal como texto en mandarín estándar, o en true para conservar las expresiones dialectales.vocabulary_id string(Opcional)El ID de una lista de palabras clave precompilada.Genere este ID con antelación llamando a la API de creación de lista de palabras clave. Pase el ID durante el reconocimiento para usar las palabras clave de la lista.Adecuado para escenarios donde el vocabulario es conocido y relativamente estable, y donde necesita reutilizar la misma lista de palabras en distintas solicitudes.Para obtener detalles sobre el uso, consulte Palabras clave precompiladas.vocabulary object(Opcional)Palabras clave instantáneas.Se pasan como pares clave-valor, donde la clave es el texto de la palabra clave (string) y el valor es el peso de la palabra clave (integer). No es necesario crear una lista de palabras clave con antelación. El peso oscila entre [1, 5] o se establece en 50: un valor en [1, 5] hace que el modelo tenga más probabilidades de generar la palabra a medida que aumenta el valor; un valor de 50 designa una súper palabra clave, lo que mejora enormemente la recuperación, pero el número de súper palabras clave no puede exceder 50.Adecuado para la optimización temporal de palabras clave a nivel de sesión.Cuando las palabras clave instantáneas y precompiladas se configuran juntas, el sistema fusiona ambos conjuntos. Si el conjunto fusionado contiene más de 2000 palabras clave, el sistema selecciona aleatoriamente 2000 para usar. Para detalles de uso, consulte Palabras clave instantáneas.channel_id array[integer](Opcional)El índice de las pistas de audio a reconocer en un archivo de audio multipista. El índice comienza en 0. Por ejemplo, [0] reconoce la primera pista, y [0, 1] reconoce la primera y la segunda pista simultáneamente. Si omite este parámetro, solo se procesa la primera pista.
Cada pista especificada se factura de forma independiente. Por ejemplo, solicitar [0, 1] para un solo archivo incurre en dos cargos separados.
Valor predeterminado: [0].special_word_filter string(Opcional)Las palabras sensibles a procesar durante el reconocimiento de voz. Puede establecer un método de manejo diferente para cada palabra sensible. Para más detalles, consulte Filtrado de palabras sensibles.diarization_enabled boolean(Opcional)Si se debe habilitar la diarización de hablantes. Deshabilitado de forma predeterminada.Se aplica solo a audio monoaural. El audio multicanal no admite la diarización de hablantes.Cuando está habilitado, el resultado del reconocimiento incluye un campo speaker_id que distingue a los diferentes hablantes.
Cuando la diarización de hablantes está habilitada, mantenga la duración del audio dentro de 2 horas. De lo contrario, el reconocimiento puede fallar o agotar el tiempo de espera.
Para ver un ejemplo de speaker_id, consulte Descripción del resultado de reconocimiento.Valor predeterminado: false.speaker_count integer(Opcional)
Surte efecto solo cuando la diarización de hablantes está habilitada (diarization_enabled está configurado en true).
Un valor de referencia para el número de hablantes. El rango válido es un entero de 2 a 100 (inclusive).De forma predeterminada, el número de hablantes se detecta automáticamente. Si configura este valor, solo guía al algoritmo para generar el recuento especificado cuando sea posible y no garantiza ese recuento exacto.Sin valor predeterminado.language_hints array[string](Opcional)Los códigos de idioma a reconocer. Si no puede determinar el idioma con antelación, déjelo sin configurar y el modelo detectará el idioma automáticamente.Puede especificar hasta 4 valores. Si especifica más, solo se aplican los primeros 4.
  • zh: Chino
  • en: Inglés
  • ja: Japonés
  • ko: Coreano
  • vi: Vietnamita
  • th: Tailandés
  • id: Indonesio
  • ms: Malayo
  • tl: Filipino
  • hi: Hindi
  • ar: Árabe
  • fr: Francés
  • de: Alemán
  • es: Español
  • pt: Portugués
  • ru: Ruso
  • it: Italiano
  • nl: Neerlandés
  • sv: Sueco
  • da: Danés
  • fi: Finés
  • no: Noruego
  • el: Griego
  • pl: Polaco
  • cs: Checo
  • hu: Húngaro
  • ro: Rumano
  • bg: Búlgaro
  • hr: Croata
  • sk: Eslovaco
  • Llamada básica
  • Palabras clave en línea
  • Context
El siguiente ejemplo utiliza la región Singapore. Reemplace "{WorkspaceId}" con su ID de espacio de trabajo real. La configuración varía según la región. La región Singapore y la región de Beijing utilizan diferentes claves de API.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-Async: enable" \
     --data '{
    "model": "qwen-audio-3.1-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "channel_id": [0]
    }
}'

Cuerpo de respuesta

request_idstringEl identificador único de esta llamada.outputobjectLos datos devueltos por la interfaz de envío de tareas.

Propiedades

task_idstringEl ID de la tarea. Pase este ID como la cadena en la Interfaz de consulta de tareas.task_statusstringEl estado de la tarea. Devuelve PENDING tras un envío exitoso.
{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}

Interfaz de consulta de tareas

Consulta el estado de ejecución y el resultado de una tarea de reconocimiento de voz. Sondee esta interfaz hasta que la tarea alcance un estado terminal.

Cuerpo de la solicitud

task_idstring(Obligatorio)
Este parámetro es un parámetro de ruta de URL. No hay cuerpo de solicitud.
Para consultar una tarea, especifique su ID. Este ID es el task_id devuelto cuando se llama a la Interfaz de envío de tareas.		El siguiente ejemplo utiliza la región de Singapur. Reemplace "{WorkspaceId}" con su ID de espacio de trabajo real. La configuración varía según la región. La región de Singapur y la región de Beijing utilizan diferentes claves de API.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Cuerpo de respuesta

request_idstringEl identificador único de esta llamada.outputobjectLos datos devueltos por la interfaz de consulta de tareas.

Propiedades

task_idstringEl ID de la tarea consultada.task_statusstringEl estado de la tarea consultada.
Cuando una tarea contiene múltiples subtareas, el estado general de la tarea se marca como SUCCEEDED siempre que cualquier subtarea tenga éxito. Compruebe el campo subtask_status para determinar el resultado de una subtarea específica.
submit_timestringLa hora en que se envió la tarea.scheduled_timestringLa hora en que se programó la ejecución de la tarea.end_timestringLa hora en que finalizó la tarea.resultsarray[object]La lista de resultados de subtareas, uno por cada archivo de audio a reconocer.
subtask_statusstringEl estado de la subtarea.file_urlstringLa URL del archivo procesado por la tarea de transcripción de archivos.transcription_urlstringEl enlace al resultado del reconocimiento. Este enlace es válido por 24 horas. Una vez que caduca, no puede consultar la tarea ni descargar el resultado a través de la URL devuelta por una consulta anterior.El resultado del reconocimiento se guarda como un archivo JSON. Puede descargar el archivo a través del enlace anterior o leer su contenido directamente con una solicitud HTTP. Para conocer el significado de cada campo en los datos JSON, consulte Descripción del resultado de reconocimiento.codestring
Se devuelve solo cuando falla la subtarea.
El código de error de la subtarea fallida.messagestring
Se devuelve solo cuando falla la subtarea.
El mensaje de error de la subtarea fallida.
task_metricsobjectEstadísticas generales de ejecución de la tarea.
TOTALintegerEl número total de subtareas.SUCCEEDEDintegerEl número de subtareas exitosas.FAILEDintegerEl número de subtareas fallidas.
{
  "request_id": "f9e1afad-94d3-997e-a83b-************",
  "output": {
    "task_id": "f86ec806-4d73-485f-a24f-************",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-09-12 15:11:40.041",
    "scheduled_time": "2024-09-12 15:11:40.071",
    "end_time": "2024-09-12 15:11:40.903",
    "results": [
      {
        "file_url": "{YOUR_AUDIO_URL}",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 1,
      "SUCCEEDED": 1,
      "FAILED": 0
    }
  },
  "usage": {
    "duration": 9
  }
}

Otras interfaces: consulta por lotes del estado de tareas / cancelar una tarea

Para más detalles, consulte Gestión de tareas asíncronas: puede consultar en lote las tareas de reconocimiento de voz no en tiempo real enviadas en las últimas 24 horas y cancelar tareas en estado PENDING (en cola).

Descripción del resultado de reconocimiento

El resultado del reconocimiento se guarda como un archivo JSON. 
{
    "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":3720,
            "text":"Hello world, this is Alibaba Speech Lab.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is Alibaba Speech Lab.",
                    "sentence_id":1,
                    "speaker_id":0, //This field is displayed only when automatic speaker diarization is enabled
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // Other content is omitted here
                    ]
                }
            ]
        }
    ]
}
Los siguientes parámetros son dignos de mención:
ParámetroTipoDescripción
audio_formatstringEl formato de audio del archivo fuente.
channelsarray[integer]El índice de pista del audio en el archivo fuente. Para audio de una sola pista, se devuelve [0]; para audio de doble pista, se devuelve [0, 1]; y así sucesivamente.
original_sampling_rateintegerLa frecuencia de muestreo (Hz) del audio en el archivo fuente.
original_duration_in_millisecondsintegerLa duración original del audio (ms) en el archivo fuente.
channel_idintegerEl índice de pista del resultado de la transcripción, comenzando desde 0.
content_durationintegerLa duración (ms) del contenido en la pista que se identifica como voz.
La descripción de facturación siguiente se aplica a qwen-audio-3.0-asr-flash-filetrans. qwen-audio-3.1-asr-flash-filetrans se factura según el uso de tokens.
El servicio de modelo de reconocimiento de voz transcribe únicamente el contenido de una pista identificada como voz, y realiza la medición y facturación basándose en dicha duración. El contenido que no es de voz no se mide ni se factura. Por lo general, la duración del contenido de voz es menor que la duración del audio original. Dado que la existencia de contenido de voz es determinada por un modelo de IA, el resultado puede diferir ligeramente de la situación real.
transcriptstringEl resultado de la transcripción a nivel de párrafo.
sentencesarrayEl resultado de la transcripción a nivel de oración.
wordsarrayEl resultado de la transcripción a nivel de palabra.
begin_timeintegerLa marca de tiempo de inicio (ms).
end_timeintegerLa marca de tiempo de finalización (ms).
textstringEl resultado de la transcripción.
speaker_idintegerEl índice del hablante actual, comenzando desde 0, utilizado para distinguir entre diferentes hablantes.Este campo aparece en el resultado del reconocimiento solo cuando la diarización de hablantes está habilitada.
punctuationstringLa puntuación predicha después de la palabra, si la hay.