Skip to main content

SDK de Python para reconocimiento de voz no en tiempo real de Fun-ASR

Este tema describe los parámetros e interfaces del SDK de Python para reconocimiento de voz no en tiempo real de Fun-ASR.

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.

Requisitos previos

Inicio rápido

Los siguientes ejemplos usan DashScope Python SDK 2.0. El Recurso principal (client.audio.asr) proporciona métodos para enviar, esperar y consultar tareas de las dos formas siguientes:
  • Enviar la tarea de forma asíncrona y esperar de forma síncrona: después de enviar la tarea, bloquee el hilo actual hasta que finalice la tarea y devuelva el resultado de reconocimiento.
  • Enviar la tarea de forma asíncrona y consultar el resultado de forma asíncrona: después de enviar la tarea, llame a la interfaz de consulta para recuperar el resultado cuando lo necesite.
  • Enviar de forma asíncrona y esperar de forma síncrona
  • Enviar de forma asíncrona y consultar el resultado de forma asíncrona
Enviar una tarea y esperar
  1. Llame a client.audio.asr.jobs.create para enviar una tarea con los parámetros de solicitud.
    • El servicio de transcripción de archivos procesa las tareas enviadas a través de la API con el mejor esfuerzo posible. Después de enviar una tarea, esta entra en el estado de en cola (PENDING). El tiempo de espera depende de la longitud de la cola y de la duración del archivo, por lo que no se puede determinar con precisión, pero generalmente es de unos pocos minutos. Una vez que comienza el procesamiento, el reconocimiento de voz se completa a una velocidad cientos de veces superior al tiempo real.
    • Después de que finaliza cada tarea, el resultado de reconocimiento y la URL de descarga son válidos durante 24 horas. Después de su caducidad, ya no podrá consultar la tarea ni descargar el resultado a través de la URL devuelta en una consulta anterior.
  2. Llame a client.audio.asr.jobs.wait(job=job) para esperar a que finalice de forma síncrona. Mientras la tarea esté en PENDING o RUNNING, jobs.wait sigue esperando. Devuelve un Job cuando la tarea se completa correctamente. Los métodos devuelven un Job. Lea la lista de resultados en job.results; cada transcription_url apunta a un resultado de transcripción descargable.
import json
import os

import dashscope

# Sustituya {WorkspaceId} por el ID real del espacio de trabajo de la región.
client = dashscope.Client(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

job = client.audio.asr.jobs.create(
    model="fun-asr",
    file_urls=["{YOUR_AUDIO_URL}"],
)

job = client.audio.asr.jobs.wait(job=job)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))

Endpoints de servicio

El SDK usa la región de Pekín de forma predeterminada. Al crear dashscope.Client, especifique la región en region y el ID del espacio de trabajo en workspace. La configuración de región se aplica solo a este Client.
  • Singapore
  • China (Beijing)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
Las claves de API varían entre regiones. Use la clave de la región correspondiente.

Parámetros de solicitud

Configure los parámetros mediante client.audio.asr.transcribe o client.audio.asr.jobs.create.
ParámetroTipoObligatorioDescripción
modelstrSíEl nombre del modelo.
file_urlslist[str]Sí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.
parameters.vocabulary_idstrNoEl 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.
parameters.vocabularydictNoPalabras clave instantáneas. Pase pares clave-valor cuyas claves sean los textos de las palabras clave (string) y cuyos valores sean pesos enteros (integer). No es necesario crear una lista precompilada.Para conocer su uso, consulte Palabras clave instantáneas.Ejemplo:El siguiente ejemplo reutiliza el client configurado con la región y el espacio de trabajo en Inicio rápido.
vocab = {"Zhang San": 5, "Li Si": 5}
result = client.audio.asr.jobs.create(
    model="fun-asr",
    file_urls=["{YOUR_AUDIO_URL}"],
    parameters={"vocabulary": vocab},
)
parameters.channel_idlist[int]NoEl í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].
parameters.special_word_filterstrNoLas 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.
parameters.diarization_enabledboolNoSi 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.
Valor predeterminado: False.Para ver un ejemplo de speaker_id, consulte Descripción del resultado de reconocimiento.
parameters.speaker_countintNo
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.
parameters.language_hintslist[str]NoLos 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 1 valor. Si especifica más, solo se aplican los primeros 1.
  • 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

Respuesta

Job

Job contiene información de la tarea, salida sin procesar y uso.
{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "status": "PENDING",
    "submitted_at": "2026-10-29 10:00:00.000",
    "scheduled_at": null,
    "finished_at": null,
    "output": {
        "task_id": "00000000-0000-0000-0000-000000000001",
        "task_status": "PENDING",
        "submit_time": "2026-10-29 10:00:00.000"
    },
    "usage": null
}
CampoDescripción
task_idEl ID de la tarea.
statusEl estado de la tarea: PENDING, RUNNING, SUCCEEDED o FAILED.
submitted_atLa hora de envío, correspondiente a job.output["submit_time"].
scheduled_atEl inicio del procesamiento, correspondiente a job.output["scheduled_time"].
finished_atLa hora de finalización, correspondiente a job.output["end_time"].
outputEl diccionario de salida sin procesar de la tarea.
resultsLa lista de resultados de subtareas, accesible mediante job.results. Descargue el archivo JSON de transcription_url para obtener el texto reconocido.
usageInformación de uso de la tarea.

Job.output

job.output es el diccionario de salida sin procesar de la tarea devuelto por el servicio.
  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED (raise_on_error=False)
{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "task_status": "PENDING",
    "submit_time": "2026-10-29 10:00:00.000"
}
ParámetroDescripción
codeEl código de error. Combínelo con el campo message y consulte Códigos de error para solucionar el problema.
messageEl mensaje de error. Combínelo con el campo code y consulte Códigos de error para solucionar el problema.
task_idID de tarea.
task_statusEstado de la tarea.Uno de cuatro estados: PENDING, RUNNING, SUCCEEDED y FAILED.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 cada subtarea.
resultsResultados de reconocimiento de la subtarea.
subtask_statusEstado de la subtarea.Uno de cuatro estados: PENDING, RUNNING, SUCCEEDED y FAILED.
file_urlURL del audio reconocido.
transcription_urlURL del resultado de reconocimiento de audio.El resultado de reconocimiento se guarda como un archivo JSON. Puede descargar el archivo desde el enlace asociado con transcription_url o leer su contenido directamente mediante una solicitud HTTP. Para ver el contenido del archivo JSON, consulte Descripción del resultado de reconocimiento.

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.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.

Interfaces clave

Recurso principal (client.audio.asr)

Cree un cliente con dashscope.Client y use el recurso client.audio.asr. Todos los métodos siguientes devuelven un Job.
MétodoFirma del métodoDescripción
transcribe
def transcribe(
    file_urls: List[str],
    *,
    model: str = "qwen-audio-3.1-asr-flash-filetrans",
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: float = 86400.0,
    submit_timeout: Optional[float] = None,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
Envíe una tarea y espere su finalización de forma síncrona. El modelo predeterminado es qwen-audio-3.1-asr-flash-filetrans. Especifique model explícitamente para llamar a otro modelo.
jobs.create
def create(
    *,
    model: str,
    file_urls: List[str],
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
Envíe una tarea y devuelva un Job con task_id y status, sin esperar a que finalice el reconocimiento.
jobs.wait
def wait(
    job: Union[Job, str],
    *,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    timeout: float = 86400.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
Pase un Job o ID de tarea y espere la finalización de forma síncrona. Configure los intervalos inicial y máximo de consulta con poll_interval y max_interval, y el tiempo total de espera con timeout. Todos los valores están en segundos.
jobs.fetch
def fetch(
    task_id: str,
    *,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
Consulte el estado y los resultados una vez mediante el ID de tarea, sin esperar su finalización.

Códigos de error

De forma predeterminada, una tarea fallida genera DashScopeError. Para recibir un Job fallido, configure raise_on_error=False al crear el Client y compruebe job.status. Si encuentra un error, consulte Códigos de error para solucionar el problema. Cuando una tarea contiene múltiples subtareas, el estado general de la tarea se marca como SUCCEEDED siempre que al menos una subtarea tenga éxito. Verifique el campo subtask_status para determinar el resultado de cada subtarea. Ejemplo de respuesta de error:
{
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "results": [
        {
            "file_url": "{YOUR_AUDIO_URL}",
            "code": "InvalidFile.DownloadFailed",
            "message": "The audio file cannot be downloaded.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

FAQ

Funcionalidades

P: ¿Se admite audio codificado en Base64?

No se admite audio codificado en Base64. Solo se puede reconocer audio en una URL de acceso público. Las secuencias binarias y los archivos locales no se pueden reconocer directamente.

P: ¿Cómo puedo hacer que un archivo de audio esté disponible en una URL de acceso público?

Los pasos típicos son los siguientes. Este es un enfoque; el proceso exacto varía según el producto de almacenamiento. Le recomendamos que cargue el audio en Alibaba Cloud OSS:
Por ejemplo:
  • Servicio de almacenamiento de objetos (recomendado):
    • Utilice el servicio de almacenamiento de objetos de un proveedor de servicios en la nube (como Alibaba Cloud OSS) para cargar el archivo de audio en un bucket y configurarlo como acceso público.
    • Ventajas: alta disponibilidad, soporte de aceleración CDN y gestión sencilla.
  • Servidor web:
    • Coloque el archivo de audio en un servidor web que admita acceso HTTP/HTTPS (como Nginx o Apache).
    • Ventajas: adecuado para proyectos pequeños o pruebas locales.
  • Red de entrega de contenido (CDN):
    • Aloje el archivo de audio en una CDN y acceda a él a través de la URL proporcionada por la CDN.
    • Ventajas: acelera la entrega de archivos y es adecuado para escenarios de alta concurrencia.
Cargue el audio según el método de almacenamiento o alojamiento que haya elegido. Por ejemplo:
  • Servicio de almacenamiento de objetos:
    • Inicie sesión en la consola del proveedor de servicios en la nube y cree un bucket.
    • Cargue el archivo de audio y configure su permiso como lectura pública o genere un enlace de acceso temporal.
  • Servidor web:
    • Coloque el archivo de audio en un directorio designado del servidor (como /var/www/html/audio/).
    • Asegúrese de que el archivo sea accesible mediante HTTP/HTTPS.
Por ejemplo:
  • Servicio de almacenamiento de objetos:
    • Después de cargar el archivo, el sistema genera automáticamente una URL de acceso público (generalmente en el formato https://<bucket-name>.<region>.aliyuncs.com/<file-name>).
    • Para un nombre de dominio más amigable, vincule un dominio personalizado y habilite HTTPS.
  • Servidor web:
    • La URL de acceso suele ser la dirección del servidor más la ruta del archivo (como https://your-domain.com/audio/file.mp3).
  • CDN:
    • Después de configurar la aceleración CDN, utilice la URL proporcionada por la CDN (como https://cdn.your-domain.com/audio/file.mp3).
Asegúrese de que la URL generada sea accesible a través de la red pública. Por ejemplo:
  • Abra la URL en un navegador y verifique si el archivo de audio se reproduce.
  • Utilice una herramienta (como curl o Postman) para verificar que la URL devuelva la respuesta HTTP correcta (código de estado 200).
Al utilizar el SDK, si los archivos de audio están almacenados en Alibaba Cloud OSS, no se admiten URLs temporales con el prefijo oss://. Al utilizar la API RESTful, si los archivos de audio están almacenados en Alibaba Cloud OSS, se admiten URLs temporales con el prefijo oss://:
  • La URL temporal es válida durante 48 horas y no se puede utilizar después de su caducidad. No la utilice en un entorno de producción.
  • La API para obtener una credencial de carga está limitada a 100 QPS y no admite escalado horizontal. No la utilice en entornos de producción, escenarios de alta concurrencia o escenarios de pruebas de estrés.
  • Para entornos de producción, utilice un servicio de almacenamiento estable como OSS para garantizar la disponibilidad de archivos a largo plazo y evitar problemas de limitación de tasa.

P: ¿Cuánto tiempo tarda en obtenerse el resultado de reconocimiento?

Después de enviar una tarea, esta entra en estado de espera (PENDING). El tiempo de espera depende de la longitud de la cola y la duración del audio, por lo que no se puede indicar con exactitud, pero generalmente es de unos pocos minutos. En general, cuanto más largo sea el audio, más tiempo tardará.

Solución de problemas

Si encuentra un error de código, resuelva el problema basándose en la información de Códigos de error.

P: ¿El sondeo nunca devuelve un resultado?

Esto puede deberse a una limitación de tasa. Espere un momento e inténtelo de nuevo.

P: ¿Por qué no se puede reconocer el habla (sin resultado de reconocimiento)?

Verifique que el formato de audio y la frecuencia de muestreo sean correctos y cumplan con las restricciones de los parámetros. Utilice la herramienta ffprobe para obtener el contenedor de audio, códec, frecuencia de muestreo, canales y otros detalles:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx