Skip to main content

API HTTP de reconhecimento de fala não em tempo real do Fun-ASR

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.

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:
  1. 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_id exclusivo para indicar que a tarefa foi criada com sucesso.
  2. Etapa 2: Recupere o resultado.
    • O cliente usa o task_id retornado para consultar repetidamente a interface de verificação.
    • Quando a tarefa termina, a interface de consulta retorna o resultado final do reconhecimento.

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.
O Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:
  • China (Beijing): de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: de dashscope-intl.aliyuncs.com para {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Ao enviar uma tarefa com o novo domínio (https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com), o corpo da solicitação deve incluir o objeto parameters. Mesmo que não seja necessário definir parâmetros, passe um objeto vazio {}. Caso contrário, a tarefa será enviada com sucesso, mas o reconhecimento falhará.

Cabeçalhos da solicitação

ParâmetroTipoObrigatórioDescrição
AuthorizationstringSimToken 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-TypestringSimTipo de mídia do corpo da solicitação. Obrigatório apenas para a interface de envio de tarefa. Valor fixo: application/json.
X-DashScope-AsyncstringSimFlag 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

  • Chamada básica
  • Hotwords inline
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.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
         --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
         --header "Content-Type: application/json" \
         --header "X-DashScope-Async: enable" \
         --data '{
        "model": "fun-asr",
        "input": {
            "file_urls": [
                "{YOUR_AUDIO_URL}"
            ]
        },
        "parameters": {
            "channel_id": [0]
        }
    }'
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://.
  • Uma URL temporária é válida por 48 horas e não pode ser usada após expirar. Não a utilize em produção.
  • A interface de credencial de upload tem limite de taxa de 100 QPS e não pode ser escalonada. Não a utilize em cenários de produção, alta concorrência ou testes de carga.
  • Para produção, use armazenamento estável, como Alibaba Cloud OSS, para manter os arquivos disponíveis a longo prazo e evitar limitações de taxa.
  • Se uma URL de arquivo de áudio definida como URL pública temporária do OSS estiver inacessível, defina X-DashScope-OssResourceResolve como enable no cabeçalho da solicitação (não recomendado). O SDK não permite configurar cabeçalhos de solicitação.
parametersobject(Opcional)Objeto de parâmetro da solicitação.
Ao usar o novo domínio (https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com), parameters é obrigatório. Mesmo que não seja necessário definir parâmetros, passe um objeto vazio {}. Se você omitir este campo, a tarefa será enviada com sucesso, mas a interface de consulta retornará falha no reconhecimento.

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.
Cada faixa especificada é faturada independentemente. Por exemplo, solicitar [0, 1] para um único arquivo gera duas cobranças separadas.
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:
  • filter_with_signed.word_list: Array de strings com as palavras a substituir pelo mesmo número de caracteres *.
  • filter_with_empty.word_list: Array de strings com as palavras a remover do resultado.
  • system_reserved_filter: Booleano, padrão true, que controla se a lista integrada também será usada. As regras personalizadas continuam ativas quando é false.
Se o parâmetro for omitido, as palavras que corresponderem à lista integrada de palavras sensíveis do Model Studio serão substituídas pelo mesmo número de caracteres *.Por exemplo, substitua PROJECT por asteriscos do mesmo tamanho e remova REPORT com o valor abaixo:
{
  "special_word_filter": "{\"filter_with_signed\":{\"word_list\":[\"PROJECT\"]},\"filter_with_empty\":{\"word_list\":[\"REPORT\"]},\"system_reserved_filter\":true}"
}
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.
Para um exemplo de speaker_id, consulte Recognition result description.Valor padrão: false.speaker_count integer(Opcional)
Tem efeito apenas quando a diarização de falantes está ativada (diarization_enabled definido como true).
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.
  • zh: Chinês
  • en: Inglês
  • ja: Japonês
  • ko: Coreano
  • vi: Vietnamita
  • th: Tailandês
  • id: Indonésio
  • ms: Malaio
  • tl: Filipino
  • hi: Hindi
  • ar: Árabe
  • fr: Francês
  • de: Alemão
  • es: Espanhol
  • pt: Português
  • ru: Russo
  • it: Italiano
  • nl: Holandês
  • sv: Sueco
  • da: Dinamarquês
  • fi: Finlandês
  • no: Norueguês
  • el: Grego
  • pl: Polonês
  • cs: Tcheco
  • hu: Húngaro
  • ro: Romeno
  • bg: Búlgaro
  • hr: Croata
  • sk: Eslovaco

Corpo da resposta

{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}
request_idstringIdentificador exclusivo desta chamada.
outputobjectDados retornados pela interface de envio de tarefa.

Propriedades

task_idstringID 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.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
         --header "Authorization: Bearer $DASHSCOPE_API_KEY"
task_idstring(Obrigatório)
Este parâmetro é um parâmetro de caminho da URL. Não há corpo de solicitação.
Para consultar uma tarefa, especifique seu ID. Este ID é o task_id retornado ao chamar a Submit task interface.

Corpo da resposta

{
  "request_id": "f9e1afad-94d3-997e-a83b-************",
  "output": {
    "task_id": "f86ec806-4d73-485f-a24f-************",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-09-12 15:11:40.041",
    "scheduled_time": "2024-09-12 15:11:40.071",
    "end_time": "2024-09-12 15:11:40.903",
    "results": [
      {
        "file_url": "{YOUR_AUDIO_URL}",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 1,
      "SUCCEEDED": 1,
      "FAILED": 0
    }
  },
  "usage": {
    "duration": 9
  }
}
request_idstringIdentificador exclusivo desta chamada.
outputobjectDados retornados pela interface de consulta de tarefa.

Propriedades

task_idstringID 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.
submit_timestringHorá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.
subtask_statusstringStatus 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.codestring
Retornado apenas quando a subtarefa falha.
Código de erro da subtarefa com falha.messagestring
Retornado apenas quando a subtarefa falha.
Mensagem de erro da subtarefa com falha.
task_metricsobjectEstatísticas gerais de execução da tarefa.
TOTALintegerNú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.
{
    "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
                    ]
                }
            ]
        }
    ]
}
Os seguintes parâmetros merecem atenção:
ParâmetroTipoDescrição
audio_formatstringFormato de áudio do arquivo de origem.
channelsarray[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_rateintegerTaxa de amostragem (Hz) do áudio no arquivo de origem.
original_duration_in_millisecondsintegerDuração original do áudio (ms) no arquivo de origem.
channel_idintegerÍndice da faixa do resultado da transcrição, começando em 0.
content_durationintegerDuraçã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.
transcriptstringResultado da transcrição no nível de parágrafo.
sentencesarrayResultado da transcrição no nível de sentença.
wordsarrayResultado da transcrição no nível de palavra.
begin_timeintegerCarimbo de data/hora inicial (ms).
end_timeintegerCarimbo de data/hora final (ms).
textstringResultado da transcrição.
speaker_idintegerÍ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.
punctuationstringPontuação prevista após a palavra, se houver.