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 Qwen-Audio-3.0-ASR-Flash-Filetrans e Fun-ASR.
Guia do usuário:Non-real-time speech recognition. 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 |
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: |
X-DashScope-Async | string | Sim | Flag de tarefa assíncrona. Obrigatória apenas para a interface de envio de tarefa. Valor fixo: |
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)Nome do modelo. Os valores compatíveis incluem as famílias de modelos Qwen-Audio-3.0-ASR-Flash-Filetrans e Fun-ASR. Para mais detalhes, consulte Supported models and regions. | |
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://.contextarray(object)(Opcional)Lista de mensagens que fornecem contexto opcional de conversa para melhorar a precisão do reconhecimento.
Propriedades role string(Obrigatório)Função da mensagem. Valores válidos:
array(object)(Obrigatório)Lista de itens de conteúdo da mensagem.
Propriedades type string(Obrigatório)Tipo de conteúdo. Valores válidos:
string(Condicionalmente obrigatório)Quando type for input_text, insira os resultados de reconhecimento da fala do usuário de turnos anteriores ou uma lista de palavras específicas de domínio. Quando type for text, insira as respostas do modelo de linguagem grande de turnos anteriores. O texto é contado caractere a caractere. O comprimento combinado dos campos text em todas as mensagens de um turno de contexto não deve exceder 400 caracteres. Qualquer excesso será truncado a partir do final. | |
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.Passadas como pares chave-valor, onde a chave é o texto da hotword (string) e o valor é o peso da hotword (integer). Não é necessário criar lista de hotwords antecipadamente. O peso varia de [1, 5] ou é definido como 50: um valor em [1, 5] aumenta a probabilidade de o modelo gerar a palavra à medida que o valor cresce; um valor de 50 designa uma super hotword, o que melhora muito o recall, mas o número de super hotwords não pode exceder 50.Adequado para otimização temporária de hotwords no nível de sessão.Quando configuradas junto com hotwords pré-compiladas, apenas as hotwords instantâneas entram em vigor. Para detalhes de uso, consulte Instant hotwords.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)Palavras sensíveis a serem processadas durante o reconhecimento de fala. Você pode definir um método de tratamento diferente para cada palavra sensível. Para detalhes, consulte Sensitive word filtering.diarization_enabled 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.Para modelos Qwen-Audio-3.0-ASR-Flash-Filetrans, você pode definir até 4 valores; quaisquer valores além dos primeiros 4 serão ignorados. Para modelos Fun-ASR, você pode definir apenas 1 valor; se definir vários, apenas o primeiro terá efeito.
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.
Clique em para visualizar o exemplo de resultado do reconhecimento
Clique em para visualizar o exemplo de resultado do reconhecimento
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. |