SDK de Python para reconocimiento de voz no en tiempo real de Paraformer

Alibaba Cloud Model Studio ha lanzado un dominio específico de espacio de trabajo para la región China (Beijing). El nuevo dominio dedicado ofrece un rendimiento superior y mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar de dashscope.aliyuncs.com a {WorkspaceId}.cn-beijing.maas.aliyuncs.com.Reemplace {WorkspaceId} con su ID de espacio de trabajo real. El dominio existente permanece totalmente funcional.

Guía del usuario:Reconocimiento de voz no en tiempo real

Requisitos previos

Ha activado el servicio y ha seguido los pasos para Obtener una clave de API. Por favor, Configure la clave de API como una variable de entorno en lugar de codificarla directamente en su código para prevenir riesgos de seguridad causados por fugas de código.

Cuando necesite proporcionar acceso temporal a aplicaciones o usuarios externos, o cuando want controlar estrictamente operaciones de alto riesgo como acceder o eliminar datos sensibles, le recomendamos utilizar tokens de autenticación temporal.En comparación con las claves de API a largo plazo, los tokens de autenticación temporal tienen un período de validez corto (60 segundos) y mayor seguridad, lo que los hace adecuados para escenarios de llamadas temporales y reduce eficazmente el riesgo de fuga de claves de API.Uso: En su código, reemplace la clave de API utilizada originalmente para la autenticación con el token de autenticación temporal obtenido.

Instale el SDK de DashScope más reciente.

Introducción

El recurso principal (client.audio.asr) proporciona interfaces para el envío asíncrono de tareas, la espera síncrona de la finalización de tareas y la consulta asíncrona de resultados (transcribe en un solo paso, o paso a paso mediante jobs.create + jobs.wait + jobs.fetch). Puede utilizar cualquiera de los dos enfoques de llamada siguientes para el reconocimiento de voz no en tiempo real:

Envío asíncrono + espera síncrona: Envíe una tarea y bloquee hasta que se complete y devuelva el resultado.
Envío asíncrono + sondeo asíncrono: Envíe una tarea y sondee los resultados en cualquier momento.

Envío asíncrono + espera síncrona

Llame al recurso principal (client.audio.asr) (jobs.create/transcribe) y configure los parámetros de solicitud.
- El servicio de transcripción de archivos procesa las tareas enviadas a través de la API sobre la base del mejor esfuerzo. Después del envío, una tarea entra en el estado de espera (PENDING). El tiempo de espera depende de la longitud de la cola y la duración del archivo, y no se puede estimar con precisión, pero generalmente se completa en unos pocos minutos. Una vez que comienza el procesamiento, el reconocimiento de voz se completa a varios cientos de veces la velocidad en tiempo real.
- Después de que cada tarea se completa, el resultado de reconocimiento y el enlace de descarga de la URL son válidos durante 24 horas. Después de la expiración, no puede consultar la tarea ni descargar resultados a través de la URL proporcionada anteriormente.
Llame al recurso principal (client.audio.asr) (jobs.wait, o transcribe en un solo paso) para esperar sincrónicamente a que se complete la tarea. Estados de la tarea: PENDING, RUNNING, SUCCEEDED, FAILED. La llamada a wait se bloquea durante PENDING o RUNNING. Cuando la tarea alcanza SUCCEEDED o FAILED, wait devuelve el resultado. jobs.wait devuelve el Job en estado final (para la estructura, consulte Respuesta).

Haga clic para ver el ejemplo completo

import os
import json
import dashscope

# Si no ha configurado la clave de API en una variable de entorno, sustituya la siguiente línea por su propia clave de API: api_key="sk-xxx"
# La siguiente configuración corresponde a la región de China (Pekín). Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Enviar la tarea de reconocimiento de archivos grabados y esperar sincrónicamente a que se complete la tarea
job = client.audio.asr.transcribe(
    ['{YOUR_AUDIO_URL}'],
    model='paraformer-v2',
    parameters={'language_hints': ['zh', 'en']}  # El parámetro "language_hints" solo es compatible con el modelo paraformer-v2.
)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))
print('transcription done!')

CLI de dashscope

# Submit a recorded file recognition task
export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your Workspace ID, and cn-beijing with the corresponding region (Singapore: ap-southeast-1, US East: us-east-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
dashscope transcription create -m paraformer-v2 --file-url "https://example.com/audio.mp3"
# Query the task list
dashscope transcription list

El asistente interactivo SDK Expert puede realizar el mismo desarrollo y solución de problemas en lenguaje natural. Consulte DashScope SDK Expert.

Para la tabla completa de regiones, consulte Resumen de URL base.

Envío asíncrono + sondeo asíncrono

Llame al recurso principal (client.audio.asr) (jobs.create/transcribe) y configure los parámetros de solicitud.
- El servicio de transcripción de archivos procesa las tareas enviadas a través de la API sobre la base del mejor esfuerzo. Después del envío, una tarea entra en el estado de espera (PENDING). El tiempo de espera depende de la longitud de la cola y la duración del archivo, y no se puede estimar con precisión, pero generalmente se completa en unos pocos minutos. Una vez que comienza el procesamiento, el reconocimiento de voz se completa a varios cientos de veces la velocidad en tiempo real.
- Después de que cada tarea se completa, el resultado de reconocimiento y el enlace de descarga de la URL son válidos durante 24 horas. Después de la expiración, no puede consultar la tarea ni descargar resultados a través de la URL proporcionada anteriormente.
Sondee el recurso principal (client.audio.asr) (jobs.fetch) hasta que se complete la tarea. Detenga el sondeo cuando el estado sea SUCCEEDED o FAILED y procese el resultado. jobs.fetch devuelve un Job (para la estructura, consulte Respuesta).

Haga clic para ver el ejemplo completo

import os
import json
import dashscope
# La siguiente configuración corresponde a la región de China (Pekín). Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si no ha configurado la clave de API en una variable de entorno, sustituya la siguiente línea por su propia clave de API: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Enviar la tarea de reconocimiento de archivos grabados
job = client.audio.asr.jobs.create(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    parameters={'language_hints': ['zh', 'en']}  # El parámetro "language_hints" solo es compatible con el modelo paraformer-v2.
)

# Sondear la tarea hasta que se devuelva el resultado final
while True:
    if job.status == 'SUCCEEDED' or job.status == 'FAILED':
        break
    job = client.audio.asr.jobs.fetch(job.task_id)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))
print('transcription done!')

Parámetros de solicitud

Pase estos parámetros al método jobs.create/transcribe del recurso principal (client.audio.asr).

Parámetro	Tipo	Predeterminado	Obligatorio	Descripción
model	str		Sí	El nombre del modelo para la transcripción de archivos de audio y video de Paraformer. Modelos admitidos.
file_urls	list[str]		Sí	Una lista de URLs para la transcripción de archivos de audio y video. Se admiten los protocolos HTTP y HTTPS. Una sola solicitud admite solo 1 URL.Si los archivos de audio están almacenados en Alibaba Cloud OSS, el SDK no admite URL temporales con el prefijo oss://.
vocabulary_id	str		No	El ID de vocabulario personalizado. Admitido para modelos de la serie v2; requiere configuración de idioma. Deshabilitado por defecto. Vocabularios personalizados.
channel_id	list[int]	[0]	No	Especifica los índices de pista de audio a reconocer en un archivo de audio multipista. Los índices comienzan desde 0. Por ejemplo, [0] significa reconocer la primera pista, y [0, 1] significa reconocer tanto la primera como la segunda pista simultáneamente. Si se omite este parámetro, solo se procesa la primera pista por defecto. Cada pista especificada se factura de forma independiente. Por ejemplo, solicitar [0, 1] para un solo archivo incurre en dos cargos separados.
disfluency_removal_enabled	bool	False	No	Filtra palabras de relleno. Deshabilitado de forma predeterminada.
timestamp_alignment_enabled	bool	False	No	Habilita la alineación de marcas de tiempo. Deshabilitado por defecto.
special_word_filter	str		No	Especifica las palabras sensibles que se deben procesar durante el reconocimiento de voz y permite configurar diferentes métodos de procesamiento para distintas palabras sensibles.Si no se proporciona este parámetro, el sistema utiliza la lógica de filtrado de palabras sensibles incorporada, y las palabras que coincidan con la lista de palabras sensibles de Alibaba Cloud Model Studio en los resultados de reconocimiento se reemplazarán con `` de igual longitud.Si se proporciona este parámetro, se pueden implementar las siguientes estrategias de procesamiento de palabras sensibles: Reemplazar con ``: Reemplaza las palabras sensibles coincidentes con `` de igual longitud. Filtrar directamente: Elimina completamente las palabras sensibles coincidentes de los resultados de reconocimiento. El valor de este parámetro debe ser una cadena JSON con la siguiente estructura: `{ "filter_with_signed": { "word_list": ["test"] }, "filter_with_empty": { "word_list": ["start", "happen"] }, "system_reserved_filter": true }` Descripciones de los campos JSON: `filter_with_signed` Tipo: Object. Obligatorio: No. Descripción: Configura la lista de palabras sensibles que se reemplazarán con ``. Las palabras coincidentes en los resultados de reconocimiento se reemplazarán con `` de igual longitud. Ejemplo: Utilizando el JSON anterior, el resultado de reconocimiento de voz para "Ayúdame a probar este código" sería "Ayúdame a *** este código". Campos internos: `word_list`: Una matriz de cadenas que enumera las palabras sensibles que se deben reemplazar. `filter_with_empty` Tipo: Object. Obligatorio: No. Descripción: Configura la lista de palabras sensibles que se eliminarán (filtrarán) de los resultados de reconocimiento. Las palabras coincidentes se eliminarán por completo. Ejemplo: Utilizando el JSON anterior, el resultado de reconocimiento de voz para "El juego está a punto de comenzar, ¿verdad?" sería "El juego está a punto de, ¿verdad?". Campos internos: `word_list`: Una matriz de cadenas que enumera las palabras sensibles que se deben eliminar por completo (filtrar). `system_reserved_filter` Tipo: Boolean. Obligatorio: No. Predeterminado: true. Descripción: Indica si se deben habilitar las reglas de palabras sensibles integradas del sistema. Cuando se establece en `true`, también se habilita la lógica de filtrado de palabras sensibles integrada del sistema, y las palabras que coincidan con la lista de palabras sensibles de Alibaba Cloud Model Studio en los resultados de reconocimiento se reemplazarán con `*` de igual longitud.
language_hints	list[str]	["zh", "en"]	No	Especifica los códigos de idioma del habla que se va a reconocer.Este parámetro solo es aplicable al modelo paraformer-v2.Códigos de idioma admitidos: zh: Chino en: Inglés ja: Japonés yue: Cantonés ko: Coreano de: Alemán fr: Francés ru: Ruso
diarization_enabled	bool	False	No	Diarización automática de hablantes. Deshabilitada de forma predeterminada.Solo aplicable a audio mono. El audio multicanal no admite la diarización de hablantes.Cuando esta función está habilitada, los resultados de reconocimiento incluirán un campo `speaker_id` para distinguir a los diferentes hablantes. Si la diarización de hablantes está habilitada, se recomienda que la duración del audio no exceda 2 horas; de lo contrario, el reconocimiento podría fallar o agotar el tiempo de espera. Para un ejemplo de `speaker_id`, consulte Descripción de resultados de reconocimiento.
speaker_count	int		No	Recuento de hablantes de referencia. Entero de 2 a 100.Surte efecto solo cuando `diarization_enabled` es true.Determinado automáticamente por defecto. Establecer este parámetro guía al algoritmo pero no garantiza el recuento exacto.

Respuesta

`Job`

Un objeto Job contiene la información básica de la tarea (task_id y status) y el resultado de la ejecución (results, consulte resultados de reconocimiento de subtareas, task_metrics, usage). El Job devuelto por jobs.create tras el envío de la tarea contiene solo task_id y status; el Job devuelto por jobs.fetch, jobs.wait (y transcribe en un solo paso) contiene el resultado de la ejecución de la tarea.

Haga clic para ver ejemplos de la estructura Job

El Job devuelto por jobs.create es el siguiente (la tarea está en el estado PENDING después del envío):

{
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
    "status":"PENDING"
}

El Job devuelto por jobs.fetch, jobs.wait (y transcribe en un solo paso) es el siguiente:

{
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
    "status":"PENDING",
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":0,
        "FAILED":0
    }
}

Parámetros clave:

Parámetro	Descripción
request_id	El ID generado por el sistema para identificar esta llamada.
task_id	El ID de la tarea.
status	El estado de la tarea. Los cuatro estados son `PENDING`, `RUNNING`, `SUCCEEDED` y `FAILED`. Cuando una tarea contiene múltiples subtareas, si alguna subtarea se ejecuta correctamente, el estado de toda la tarea se marca como `SUCCEEDED`. Revise el campo `subtask_status` para determinar el resultado de cada subtarea específica.
results	Los resultados de reconocimiento de las subtareas. Cada elemento contiene `file_url`, `transcription_url` y `subtask_status`. Para obtener más información, consulte resultados de reconocimiento de subtareas.
subtask_status	El estado de la subtarea. Los cuatro estados son `PENDING`, `RUNNING`, `SUCCEEDED` y `FAILED`.
file_url	La URL del archivo de audio a reconocer.
transcription_url	La URL correspondiente al resultado de reconocimiento de audio. El resultado de reconocimiento se guarda como un archivo JSON. Descargue el archivo desde la URL en `transcription_url` o lea su contenido mediante una solicitud HTTP. Para más detalles sobre el contenido del archivo JSON, consulte Descripción del resultado de reconocimiento.
usage	La información de medición, incluida `duration` (la duración del audio, en segundos).

Cuando una llamada falla, el SDK de Python lanza una excepción DashScopeError. Puede obtener el código de error, el código de estado HTTP, el mensaje de error y el ID de solicitud mediante e.code/e.status_code/e.message/e.request_id. El fallo de una subtarea no lanza una excepción; en su lugar, verifique subtask_status, code y message en results.

`results` (resultados de reconocimiento de subtareas)

El array results contiene el resultado de reconocimiento de subtareas de cada archivo de audio en el Job. Cada elemento contiene file_url, transcription_url y subtask_status; cuando una subtarea falla, también contiene code y message.

Haga clic para ver ejemplos de la estructura results

Estado SUCCEEDED
Estado FAILED

{
    "file_url":"{YOUR_AUDIO_URL}",
    "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A59/70e737cc-bf8c-418b-b0c8-83fab192a0fa-1.json?Expires=1739527168&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
    "subtask_status":"SUCCEEDED"
}

code es el código de error y message es el mensaje de error, devueltos solo cuando falla una subtarea. Utilice estos dos campos junto con los Códigos de error para solucionar problemas.

{
    "file_url": "{YOUR_AUDIO_URL}",
    "code": "InvalidFile.DownloadFailed",
    "message": "The audio file cannot be downloaded.",
    "subtask_status": "FAILED"
}

Parámetros importantes:

Parámetro	Descripción
code	El código de error. Úselo junto con el campo `message`. Consulte Códigos de error.
message	El mensaje de error. Úselo junto con el campo `code`. Consulte Códigos de error.
subtask_status	El estado de la subtarea. Los cuatro estados son `PENDING`, `RUNNING`, `SUCCEEDED` y `FAILED`.
file_url	La URL del archivo de audio a reconocer.
transcription_url	La URL correspondiente al resultado de reconocimiento de audio. El resultado de reconocimiento se guarda en un archivo JSON. Descargue el archivo desde `transcription_url` o lea su contenido mediante una solicitud HTTP. Para más detalles sobre el contenido JSON, consulte Descripción del resultado de reconocimiento.

Descripción del resultado de reconocimiento

El resultado del reconocimiento se guarda como un archivo JSON.

Haga clic para ver el ejemplo de resultado de reconocimiento

{
    "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 the Alibaba speech laboratory.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is the Alibaba speech laboratory.",
                    "sentence_id":1,
                    "speaker_id":0, //This field is only displayed 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 omitted here
                    ]
                }
            ]
        }
    ]
}

Los parámetros clave son los siguientes:

Parámetro	Tipo	Descripción
audio_format	string	El formato de audio del archivo fuente.
channels	array[integer]	La información del índice de pistas de audio del archivo fuente. Devuelve [0] para audio mono, [0, 1] para audio de doble pista, y así sucesivamente.
original_sampling_rate	integer	La frecuencia de muestreo (Hz) del audio en el archivo fuente.
original_duration	integer	La duración original del audio (ms) del archivo fuente.
channel_id	integer	El índice de la pista de audio del resultado de transcripción, comenzando desde 0.
content_duration	integer	La duración (ms) del contenido identificado como habla en la pista de audio. El servicio de modelo de reconocimiento de voz Paraformer solo transcribe y mide el contenido identificado como voz en la pista de audio, y factura en consecuencia. El contenido que no es voz no se mide ni se factura. Normalmente, la duración del contenido de voz es menor que la duración del audio original. Dado que la determinación de si existe contenido de voz la realiza un modelo de IA, puede haber alguna desviación respecto a la situación real.
transcript	string	El resultado de la transcripción de voz a nivel de párrafo.
sentences	array	El resultado de la transcripción de voz a nivel de oración.
words	array	El resultado de la transcripción de voz a nivel de palabra.
begin_time	integer	La marca de tiempo de inicio (ms).
end_time	integer	La marca de tiempo de finalización (ms).
text	string	El resultado de la transcripción de voz.
speaker_id	integer	El índice del hablante actual, comenzando desde 0, utilizado para distinguir a los diferentes hablantes. Este campo solo se muestra en los resultados de reconocimiento cuando la diarización de hablantes está habilitada.
punctuation	string	La puntuación predicha después de la palabra (si la hay).

Referencia de API

Recurso principal (`client.audio.asr`)

La capacidad de reconocimiento de voz no en tiempo real está montada en el recurso client.audio.asr. Puede utilizar client.audio.asr.transcribe para enviar la tarea y esperar en un solo paso, o client.audio.asr.jobs para el control paso a paso.

Método miembro	Firma del método	Descripción
transcribe	`def transcribe(self, file_urls: List[str], *, model: str = "paraformer-v2", parameters: Dict = None, phrase_id: str = None, timeout: float = ..., ...) -> Job`	Envía una tarea de reconocimiento de archivos grabados y bloquea el hilo actual hasta que la tarea se complete (el estado es `SUCCEEDED` o `FAILED`).Este método devuelve un `Job`. Lea los resultados de la transcripción desde `job.results` (cada elemento contiene `transcription_url`).
jobs.create	`def create(self, *, model: str, file_urls: List[str], parameters: Dict = None, phrase_id: str = None, ...) -> Job`	Envía de forma asíncrona una tarea de reconocimiento de voz.Este método devuelve un `Job` (`job.task_id`/`job.status`).
jobs.wait	`def wait(self, task: Union[str, Job], poll_interval: float = 1, timeout: float = 86400, ...) -> Job`	Bloquea el hilo actual hasta que se complete la tarea asíncrona (sondeo con retroceso exponencial, presupuesto total predeterminado de 24 horas).Este método devuelve el `Job` en estado final.
jobs.fetch	`def fetch(self, task_id: str, ...) -> Job`	Consulta de forma asíncrona el resultado de ejecución actual de la tarea.Este método devuelve un `Job`.

Otras interfaces: Consulta por lotes del estado de tareas / Cancelar tarea

Para más detalles, consulte Gestionar tareas asíncronas: Admite la consulta por lotes de tareas de reconocimiento de voz no en tiempo real enviadas en las últimas 24 horas, y también admite cancelar tareas en estado PENDING (en cola).

Códigos de error

Si encuentra errores, consulte Códigos de error para solucionar problemas. Si el problema persiste, únase a la comunidad de desarrolladores para reportar el incidente y proporcione el Request ID para una investigación adicional. Cuando una tarea contiene múltiples subtareas, siempre que cualquier subtarea tenga éxito, el estado general de la tarea se marca como SUCCEEDED. Necesita verificar el campo subtask_status para determinar el resultado de cada subtarea. Ejemplo de respuesta de error:

{
    "request_id": "16668704-6702-9e03-8ab7-a32a5d7bb095",
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "status": "SUCCEEDED",
    "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
    }
}

Más ejemplos

Explore más ejemplos en GitHub.

FAQ

Funcionalidades

P: ¿Admite audio codificado en Base64?

No. No se admite audio codificado en Base64. Solo se admite audio accesible a través de URLs de acceso público. No se admiten flujos binarios ni el reconocimiento directo de archivos locales.

P: ¿Cómo proporcionar archivos de audio como URL de acceso público?

Generalmente, siga estos pasos (esto proporciona un enfoque general; los detalles varían según el producto de almacenamiento. Recomendamos cargar el audio en Alibaba Cloud OSS):

1. Elegir un método de almacenamiento y alojamiento

Por ejemplo:

Object Storage Service (recomendado):
- Utilice un servicio de almacenamiento de objetos de un proveedor de nube (como Alibaba Cloud OSS) para cargar archivos de audio en un bucket y configurarlos para acceso público.
- Ventajas: Alta disponibilidad, soporte de aceleración CDN, gestión sencilla.
Servidor web:
- Coloque archivos de audio en un servidor web que admita acceso HTTP/HTTPS (como Nginx o Apache).
- Ventajas: Adecuado para proyectos pequeños o pruebas locales.
Content Delivery Network (CDN):
- Aloje archivos de audio en una CDN y acceda a ellos a través de la URL proporcionada por la CDN.
- Ventajas: Entrega acelerada de archivos, adecuada para escenarios de alta concurrencia.

2. Cargar archivos de audio

Cargue archivos de audio según el método de almacenamiento/alojamiento elegido, por ejemplo:

Object Storage Service:
- Inicie sesión en la consola del proveedor de servicios en la nube y cree un bucket.
- Cargue archivos de audio y configure los permisos del archivo como "lectura pública" o genere enlaces de acceso temporal.
Servidor web:
- Coloque los archivos de audio en el directorio designado del servidor (como /var/www/html/audio/).
- Asegúrese de que los archivos sean accesibles mediante HTTP/HTTPS.

3. Generar una URL de acceso público

Por ejemplo:

Object Storage Service:
- Después de la carga, el sistema genera automáticamente una URL de acceso público (generalmente en el formato https://<bucket-name>.<region>.aliyuncs.com/<file-name>).
- Si necesita un dominio más amigable, puede vincular un dominio personalizado y habilitar HTTPS.
Servidor web:
- La URL de acceso al archivo 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).

4. Verificar la accesibilidad de la URL

En un entorno de red pública, asegúrese de que la URL generada sea accesible; por ejemplo:

Abra la URL en un navegador y verifique si el archivo de audio se puede reproducir.
Utilice herramientas (como curl o Postman) para verificar si la URL devuelve una 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 toma obtener los resultados de reconocimiento?

Después del envío, la tarea entra en un estado de espera (PENDING). El tiempo de espera depende de la longitud de la cola y la duración del archivo, y no se puede estimar con precisión, pero generalmente se completa en unos pocos minutos. Por favor, espere pacientemente. Los archivos de audio más largos requieren más tiempo de procesamiento.

Solución de problemas

Para errores de código, consulte Códigos de error.

P: ¿Qué debo hacer si los resultados de reconocimiento no están sincronizados con la reproducción de audio?

Establezca el parámetro de solicitud timestamp_alignment_enabled en true para habilitar la calibración de marcas de tiempo, lo cual sincroniza los resultados de reconocimiento con la reproducción del audio.

P: ¿Cómo manejo caracteres especiales en una URL de archivo?

Si la ruta URL del archivo contiene espacios, caracteres chinos u otros caracteres que requieran codificación, aplique la codificación porcentual a dichos caracteres antes de pasar la URL a file_urls. Por ejemplo, codifique los espacios en el nombre del archivo como %20. No vuelva a codificar una URL que ya esté codificada.

P: ¿No se pueden obtener resultados tras realizar sondeos continuos?

Esto puede deberse a limitaciones de tasa. Por favor, espere pacientemente. Si necesita ampliación de capacidad, únase a la comunidad de desarrolladores para solicitarla.

P: ¿Por qué no hay resultado de reconocimiento (incapaz de reconocer el habla)?

Verifique si el audio cumple con los requisitos (formato, tasa de muestreo).
Si está utilizando el modelo paraformer-v2, verifique si la configuración de language_hints es correcta.
Si none de lo anterior resuelve el problema, puede personalizar palabras clave para mejorar el reconocimiento de términos específicos.

Más preguntas

Visite la página de QA en GitHub.

​Requisitos previos

​Introducción

​Envío asíncrono + espera síncrona

​Envío asíncrono + sondeo asíncrono

​Parámetros de solicitud

​Respuesta

​Job

​results (resultados de reconocimiento de subtareas)

​Descripción del resultado de reconocimiento

​Referencia de API

​Recurso principal (client.audio.asr)

​Otras interfaces: Consulta por lotes del estado de tareas / Cancelar tarea

​Códigos de error

​Más ejemplos

​FAQ

​Funcionalidades

​P: ¿Admite audio codificado en Base64?

​P: ¿Cómo proporcionar archivos de audio como URL de acceso público?

​P: ¿Cuánto tiempo toma obtener los resultados de reconocimiento?

​Solución de problemas

​P: ¿Qué debo hacer si los resultados de reconocimiento no están sincronizados con la reproducción de audio?

​P: ¿Cómo manejo caracteres especiales en una URL de archivo?

P: ¿No se pueden obtener resultados tras realizar sondeos continuos?

P: ¿Por qué no hay resultado de reconocimiento (incapaz de reconocer el habla)?

​Más preguntas

Requisitos previos

Introducción

Envío asíncrono + espera síncrona

Envío asíncrono + sondeo asíncrono

Parámetros de solicitud

Respuesta

`Job`

`results` (resultados de reconocimiento de subtareas)

Descripción del resultado de reconocimiento

Referencia de API

Recurso principal (`client.audio.asr`)

Otras interfaces: Consulta por lotes del estado de tareas / Cancelar tarea

Códigos de error

Más ejemplos

FAQ

Funcionalidades

P: ¿Admite audio codificado en Base64?

P: ¿Cómo proporcionar archivos de audio como URL de acceso público?

P: ¿Cuánto tiempo toma obtener los resultados de reconocimiento?

Solución de problemas

P: ¿Qué debo hacer si los resultados de reconocimiento no están sincronizados con la reproducción de audio?

P: ¿Cómo manejo caracteres especiales en una URL de archivo?

Más preguntas