Este tópico descreve os parâmetros e os detalhes da interface da API HTTP para reconhecimento de fala não em tempo real com Fun-ASR.
Para requisitos de entrada, como formatos de áudio compatíveis, limites de tamanho de arquivo e duração, consulte Audio specifications.
Diferentemente das chamadas síncronas do DashScope, que retornam o resultado imediatamente em uma única solicitação, as chamadas assíncronas são projetadas para arquivos de áudio longos ou tarefas demoradas. Este modo utiliza um fluxo de duas etapas (envio e consulta) que evita tempos limite de solicitação causados por longas esperas:
Envia uma tarefa de reconhecimento de fala. Esta interface retorna de forma assíncrona; portanto, consulte o status da tarefa na Query task interface.
Consulta o status de execução e o resultado de uma tarefa de reconhecimento de fala. Consulte esta interface repetidamente até que a tarefa atinja um estado terminal.
Para mais detalhes, consulte Manage asynchronous tasks: você pode consultar em lote tarefas de reconhecimento de fala não em tempo real enviadas nas últimas 24 horas e cancelar tarefas no estado
O resultado do reconhecimento é salvo como arquivo JSON.
Os seguintes parâmetros merecem atenção:
Como funciona
Diferentemente das chamadas síncronas do DashScope, que retornam o resultado imediatamente em uma única solicitação, as chamadas assíncronas são projetadas para arquivos de áudio longos ou tarefas demoradas. Este modo utiliza um fluxo de duas etapas (envio e consulta) que evita tempos limite de solicitação causados por longas esperas:
-
Etapa 1: Envie a tarefa.
- O cliente envia uma solicitação de processamento assíncrono.
- Após validar a solicitação, o servidor não executa a tarefa imediatamente. Em vez disso, retorna um
task_idexclusivo para indicar que a tarefa foi criada com sucesso.
-
Etapa 2: Recupere o resultado.
- O cliente usa o
task_idretornado para consultar repetidamente a interface de verificação. - Quando a tarefa termina, a interface de consulta retorna o resultado final do reconhecimento.
- O cliente usa o
Endpoints do service
- Singapore
- China (Beijing)
Interface de envio de tarefa:
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcriptionInterface de consulta de tarefa: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Substitua {WorkspaceId} pelo seu Workspace ID real.Cabeçalhos da solicitação
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Authorization | string | Sim | Token de autenticação no formato Bearer <your_api_key>. Substitua "<your_api_key>" pela sua chave de API real. Obrigatório tanto para a interface de envio quanto para a de consulta de tarefa. |
Content-Type | string | Sim | Tipo de mídia do corpo da solicitação. Obrigatório apenas para a interface de envio de tarefa. Valor fixo: application/json. |
X-DashScope-Async | string | Sim | Flag de tarefa assíncrona. Obrigatória apenas para a interface de envio de tarefa. Valor fixo: enable. Não omita este campo, caso contrário a tarefa não poderá ser enviada. |
Interface de envio de tarefa
Envia uma tarefa de reconhecimento de fala. Esta interface retorna de forma assíncrona; portanto, consulte o status da tarefa na Query task interface.
Corpo da solicitação |
O exemplo a seguir usa a região Singapore. Substitua "{WorkspaceId}" pelo ID do seu workspace real. A configuração varia conforme a região. As regiões Singapore e Beijing usam chaves de API diferentes. |
modelstring(Obrigatório)O nome do modelo. | |
inputobject(Obrigatório)Objeto de parâmetro de entrada.
Propriedades file_urls array[string](Obrigatório)Lista de URLs dos arquivos de áudio ou vídeo a serem transcritos. HTTP e HTTPS são compatíveis. Uma única solicitação aceita apenas uma URL. Para requisitos de entrada, como formatos de áudio compatíveis, limites de tamanho de arquivo e duração, consulte Audio specifications.Se a gravação estiver armazenada no Alibaba Cloud OSS, a API RESTful aceita URLs temporárias com o prefixo oss://, enquanto o SDK não aceita URLs temporárias com o prefixo oss://. | |
parametersobject(Opcional)Objeto de parâmetro da solicitação.
Propriedades vocabulary_id string(Opcional)ID de uma lista de hotwords pré-compilada.Gere este ID antecipadamente chamando a API de criação de lista de hotwords. Passe o ID durante o reconhecimento para usar as hotwords da lista.Adequado para cenários em que o vocabulário é conhecido e relativamente estável, e quando é necessário reutilizar a mesma lista de palavras entre solicitações.Para detalhes de uso, consulte Precompiled hotwords.vocabulary object(Opcional)Hotwords instantâneas. Passe pares de chave-valor em que as chaves são os textos das hotwords (string) e os valores são pesos inteiros (integer). Não é necessário criar uma lista pré-compilada.Para saber como usar, consulte Hotwords instantâneas.channel_id array[integer](Opcional)Índice das faixas de áudio a serem reconhecidas em um arquivo multifaixa. O índice começa em 0. Por exemplo, [0] reconhece a primeira faixa e [0, 1] reconhece a primeira e a segunda faixas simultaneamente. Se você omitir este parâmetro, apenas a primeira faixa será processada.Valor padrão: [0].special_word_filter string(Opcional) Configure as palavras a substituir ou remover. O parâmetro é uma string JSON com estes campos:
*.Por exemplo, substitua PROJECT por asteriscos do mesmo tamanho e remova REPORT com o valor abaixo:boolean(Opcional)Indica se a diarização de falantes deve ser ativada. Desativada por padrão.Aplica-se apenas a áudio mono. Áudio multicanal não aceita diarização de falantes.Quando ativada, o resultado do reconhecimento inclui um campo speaker_id que distingue diferentes falantes.Com a diarização de falantes ativada, mantenha a duração do áudio dentro de 2 horas. Caso contrário, o reconhecimento pode falhar ou atingir o tempo limite. speaker_id, consulte Recognition result description.Valor padrão: false.speaker_count integer(Opcional)Valor de referência para o número de falantes. O intervalo válido é um número inteiro de 2 a 100 (inclusive).Por padrão, o sistema detecta automaticamente o número de falantes. Se você definir este valor, ele apenas orientará o algoritmo a gerar a contagem especificada quando possível, sem garantir essa contagem exata.Sem valor padrão.language_hints array[string](Opcional)Códigos de idioma a serem reconhecidos. Se não for possível determinar o idioma antecipadamente, deixe-o indefinido e o modelo detectará o idioma automaticamente.Você pode definir até 1 valor. Se definir mais, apenas os 1 primeiros serão usados.
Clique em para visualizar os códigos de idioma compatíveis
|
Corpo da resposta | |
request_idstringIdentificador exclusivo desta chamada. | |
outputobjectDados retornados pela interface de envio de tarefa.
Propriedades task_id stringID da tarefa. Passe este ID como string na Query task interface.task_statusstringStatus da tarefa. Retorna PENDING após envio bem-sucedido. |
Interface de consulta de tarefa
Consulta o status de execução e o resultado de uma tarefa de reconhecimento de fala. Consulte esta interface repetidamente até que a tarefa atinja um estado terminal.
Corpo da solicitação | O exemplo a seguir usa a região Singapore. Substitua "{WorkspaceId}" pelo ID do seu workspace real. A configuração varia conforme a região. As regiões Singapore e Beijing usam chaves de API diferentes. |
task_idstring(Obrigatório)Para consultar uma tarefa, especifique seu ID. Este ID é o task_id retornado ao chamar a Submit task interface. | |
Corpo da resposta | |
request_idstringIdentificador exclusivo desta chamada. | |
outputobjectDados retornados pela interface de consulta de tarefa.
Propriedades task_id stringID da tarefa consultada.task_statusstringStatus da tarefa consultada.Quando uma tarefa contém múltiplas subtarefas, o status geral da tarefa é marcado como SUCCEEDED desde que qualquer subtarefa tenha sucesso. Verifique o campo subtask_status para determinar o resultado de uma subtarefa específica.stringHorário em que a tarefa foi enviada.scheduled_timestringHorário em que a tarefa foi agendada para execução.end_timestringHorário em que a tarefa terminou.resultsarray[object]Lista de resultados das subtarefas, um para cada arquivo de áudio a ser reconhecido.
Propriedades subtask_status stringStatus da subtarefa.file_urlstringURL do arquivo processado pela tarefa de transcrição.transcription_urlstringLink para o resultado do reconhecimento. Este link é válido por 24 horas. Após expirar, não será possível consultar a tarefa ou baixar o resultado através da URL retornada por uma consulta anterior.O resultado do reconhecimento é salvo como arquivo JSON. Baixe o arquivo através do link acima ou leia seu conteúdo diretamente com uma solicitação HTTP. Para o significado de cada campo nos dados JSON, consulte Recognition result description.codestringCódigo de erro da subtarefa com falha.messagestringMensagem de erro da subtarefa com falha.objectEstatísticas gerais de execução da tarefa.
Propriedades TOTAL integerNúmero total de subtarefas.SUCCEEDEDintegerNúmero de subtarefas bem-sucedidas.FAILEDintegerNúmero de subtarefas com falha. |
Outras interfaces: consulta em lote de status de tarefa / cancelamento de tarefa
Para mais detalhes, consulte Manage asynchronous tasks: você pode consultar em lote tarefas de reconhecimento de fala não em tempo real enviadas nas últimas 24 horas e cancelar tarefas no estado PENDING (na fila).
Descrição do resultado do reconhecimento
O resultado do reconhecimento é salvo como arquivo JSON.
| Parâmetro | Tipo | Descrição |
|---|---|---|
audio_format | string | Formato de áudio do arquivo de origem. |
channels | array[integer] | Índice da faixa de áudio no arquivo de origem. Para áudio de faixa única, retorna [0]; para áudio de duas faixas, retorna [0, 1]; e assim por diante. |
original_sampling_rate | integer | Taxa de amostragem (Hz) do áudio no arquivo de origem. |
original_duration_in_milliseconds | integer | Duração original do áudio (ms) no arquivo de origem. |
channel_id | integer | Índice da faixa do resultado da transcrição, começando em 0. |
content_duration | integer | Duração (ms) do conteúdo na faixa identificado como fala.O service de modelo de reconhecimento de fala transcreve apenas o conteúdo de uma faixa identificado como fala, medindo e faturando com base nessa duração. Conteúdo que não seja fala não é medido nem faturado. Normalmente, a duração do conteúdo de fala é menor que a duração original do áudio. Como a existência de conteúdo de fala é determinada por um modelo de IA, o resultado pode diferir ligeiramente da situação real. |
transcript | string | Resultado da transcrição no nível de parágrafo. |
sentences | array | Resultado da transcrição no nível de sentença. |
words | array | Resultado da transcrição no nível de palavra. |
begin_time | integer | Carimbo de data/hora inicial (ms). |
end_time | integer | Carimbo de data/hora final (ms). |
text | string | Resultado da transcrição. |
speaker_id | integer | Índice do falante atual, começando em 0, usado para distinguir diferentes falantes.Este campo aparece no resultado do reconhecimento apenas quando a diarização de falantes está ativada. |
punctuation | string | Pontuação prevista após a palavra, se houver. |