SDK de Python para reconocimiento de voz no en tiempo real de Paraformer - Model Studio - Alibaba Cloud Model Studio

Utilice el SDK de Python de Paraformer para transcribir archivos de audio y video con la API de DashScope.

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

NotaCuando 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

La clase core (Transcription) admite dos enfoques de transcripción:

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 método async_call de la clase principal (Transcription) y configure los parámetros de solicitud.
Nota
- 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 método wait de la clase core (Transcription) 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.

El método wait devuelve una TranscriptionResponse.

Haga clic para ver el ejemplo completo

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import json

# If you have not configured the API Key in an environment variable,
# uncomment the following line and replace "apiKey" with your own API Key.
# import dashscope
# dashscope.api_key = "apiKey"
# China (Beijing): Replace {WorkspaceId} with your actual workspace ID. The configuration varies by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

task_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    language_hints=['zh', 'en']  # The "language_hints" parameter only supports the paraformer-v2 model.
)

transcribe_response = Transcription.wait(task=task_response.output.task_id)
if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, 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

ImportanteEl 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 método async_call de la clase principal Transcription y configure los parámetros de solicitud.
Nota
- 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 método fetch de la clase core (Transcription) hasta que se complete la tarea.

Detenga el sondeo cuando el estado sea SUCCEEDED o FAILED y procese el resultado.

El método fetch devuelve una TranscriptionResponse.

Haga clic para ver el ejemplo completo

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import json

# If you have not configured the API Key in an environment variable,
# uncomment the following line and replace "apiKey" with your own API Key.
# import dashscope
# dashscope.api_key = "apiKey"
# China (Beijing): Replace {WorkspaceId} with your actual workspace ID. The configuration varies by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

transcribe_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    language_hints=['zh', 'en']  # The "language_hints" parameter only supports the paraformer-v2 model.
)

while True:
    if transcribe_response.output.task_status == 'SUCCEEDED' or transcribe_response.output.task_status == 'FAILED':
        break
    transcribe_response = Transcription.fetch(task=transcribe_response.output.task_id)

if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
    print('transcription done!')

Parámetros de solicitud

Pase estos parámetros al método async_call de la clase core (Transcription).

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

TranscriptionResponse

Un objeto TranscriptionResponse contiene task_id, task_status y el resultado de la ejecución en la propiedad output. Consulte TranscriptionOutput.

Haga clic para ver ejemplos de la estructura TranscriptionResponse

La TranscriptionResponse devuelta por async_call no incluye submit_time ni scheduled_time.

{
    "status_code":200,
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code":null,
    "message":"",
    "output":{
        "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
        "task_status":"PENDING"
    },
    "usage":null
}

Para obtener submit_time y scheduled_time, utilice los métodos wait() o fetch() en lugar de usar directamente el valor devuelto por async_call(). El objeto TranscriptionResponse devuelto por wait() o fetch():

PENDING status

{
    "status_code":200,
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code":null,
    "message":"",
    "output":{
        "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
        "task_status":"PENDING",
        "submit_time":"2025-02-13 16:55:08.573",
        "scheduled_time":"2025-02-13 16:55:08.592",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":0,
            "FAILED":0
        }
    },
    "usage":null
}

RUNNING status

{
    "status_code":200,
    "request_id":"d9d530f1-853c-9848-a5f1-f5de59086ff7",
    "code":null,
    "message":"",
    "output":{
        "task_id":"6351feef-9694-45d2-9d32-63454f2ffb8d",
        "task_status":"RUNNING",
        "submit_time":"2025-02-13 17:31:20.681",
        "scheduled_time":"2025-02-13 17:31:20.703",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":0,
            "FAILED":0
        }
    },
    "usage":null
}

SUCCEEDED status

{
    "status_code":200,
    "request_id":"16668704-6702-9e03-8ab7-a32a5d7bb095",
    "code":null,
    "message":"",
    "output":{
        "task_id":"6351feef-9694-45d2-9d32-63454f2ffb8d",
        "task_status":"SUCCEEDED",
        "submit_time":"2025-02-13 17:31:20.681",
        "scheduled_time":"2025-02-13 17:31:20.703",
        "end_time":"2025-02-13 17:31:21.867",
        "results":[
            {
                "file_url":"{YOUR_AUDIO_URL}",
                "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A31/20ee4e4f-0404-4806-b617-c7d4c62eed19-1.json?Expires=1739525481&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
                "subtask_status":"SUCCEEDED"
            }
        ],
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    },
    "usage":{
        "duration":9
    }
}

FAILED status

{
    "status_code":200,
    "request_id":"16668704-6702-9e03-8ab7-a32a5d7bb095",
    "code":null,
    "message":"",
    "output":{
        "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
        "task_status": "FAILED",
        "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
        }
    },
    "usage":{
        "duration":9
    }
}

Parámetros clave:

Parámetro	Descripción
status_code	El código de estado de la solicitud HTTP.
code	El `code` más externo se puede ignorar. En `output.results`, el campo `code` es el código de error. Úselo junto con el campo `message` y consulte los Códigos de error para solucionar problemas.
message	El `message` más externo se puede ignorar. El campo `message` dentro de `output.results` es el mensaje de error. Úselo junto con el campo `code` y consulte los códigos de error para solucionar problemas.
task_id	El ID de la tarea.
task_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.
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.

`TranscriptionOutput`

Un objeto TranscriptionOutput es la propiedad output de un objeto TranscriptionResponse, que contiene el resultado de la ejecución de la tarea.

Haga clic para ver ejemplos de la estructura TranscriptionOutput

Estado PENDING

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"PENDING",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":0,
        "FAILED":0
    }
}

Estado RUNNING

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"RUNNING",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":0,
        "FAILED":0
    }
}

Estado SUCCEEDED

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"SUCCEEDED",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "end_time":"2025-02-13 17:59:28.828",
    "results":[
        {
            "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"
        }
    ],
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":1,
        "FAILED":0
    }
}

Estado FAILED

code es el código de error y message es el mensaje de error. Devuelto solo en caso de error. Consulte Códigos de error.

{
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "FAILED",
    "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
    }
}

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.
task_id	El ID de la tarea.
task_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.
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

Clase principal (`Transcription`)

Importe la clase Transcription: from dashscope.audio.asr import Transcription.

Método miembro Firma del método Descripción

Método miembro	Firma del método	Descripción
async_call	`@classmethod def async_call(cls, model: str, file_urls: List[str], phrase_id: str = None, api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	Envía una tarea de reconocimiento de voz de forma asíncrona. Este método devuelve TranscriptionResponse.
wait	`@classmethod def wait(cls, task: Union[str, TranscriptionResponse], api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	Bloquea el hilo actual hasta que se complete la tarea asíncrona (el estado es `SUCCEEDED` o `FAILED`). Este método devuelve TranscriptionResponse.
fetch	`@classmethod def fetch(cls, task: Union[str, TranscriptionResponse], api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	Consulta de forma asíncrona el resultado de ejecución de la tarea. Este método devuelve una TranscriptionResponse.

async_call

@classmethod
def async_call(cls,
               model: str,
               file_urls: List[str],
               phrase_id: str = None,
               api_key: str = None,
               workspace: str = None,
               **kwargs) -> TranscriptionResponse

Envía una tarea de reconocimiento de voz de forma asíncrona.

Este método devuelve TranscriptionResponse.

wait

@classmethod
def wait(cls,
         task: Union[str, TranscriptionResponse],
         api_key: str = None,
         workspace: str = None,
         **kwargs) -> TranscriptionResponse

Bloquea el hilo actual hasta que se complete la tarea asíncrona (el estado es SUCCEEDED o FAILED).

Este método devuelve TranscriptionResponse.

fetch

@classmethod
def fetch(cls,
          task: Union[str, TranscriptionResponse],
          api_key: str = None,
          workspace: str = None,
          **kwargs) -> TranscriptionResponse

Consulta de forma asíncrona el resultado de ejecución de la tarea.

Este método devuelve una TranscriptionResponse.

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:

{
    "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
    }
}

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.