Qwen-Audio-3.0-ASR-Flash-Filetrans/Fun-ASR HTTP API for non-real-time speech recognition - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

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.

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_id exclusivo para indicar que a tarefa foi criada com sucesso.
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

Interface de envio de tarefa: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription

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

China (Beijing)

Interface de envio de tarefa: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription

Interface de consulta de tarefa: GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Substitua {WorkspaceId} pelo seu Workspace ID real.

ImportanteO 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

Substitua {WorkspaceId} pelo seu Workspace ID real. Os domínios existentes permanecem totalmente funcionais.

ImportanteAo 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â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

Chamada básica

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": "qwen-audio-3.0-asr-flash-filetrans",
        "input": {
            "file_urls": [
                "{YOUR_AUDIO_URL}"
            ]
        },
        "parameters": {
            "channel_id": [0]
        }
    }'

Hotwords inline

Use hotwords inline no seguinte formato:

{
        "model": "qwen-audio-3.0-asr-flash-filetrans",
        "input": {
            "file_urls": [
                "{YOUR_AUDIO_URL}"
            ]
        },
        "parameters": {
            "vocabulary": {"John Smith": 5, "Jane Doe": 5}
        }
    }

Contexto

Use o contexto no seguinte formato:

{
        "model": "qwen-audio-3.0-asr-flash-filetrans",
        "input": {
            "file_urls": [
                "{YOUR_AUDIO_URL}"
            ],
            "context": [
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "input_text",
                            "text": "Hello there"
                        }
                    ]
                },
                {
                    "role": "assistant",
                    "content": [
                        {
                            "type": "text",
                            "text": "Hello, I am Qwen. How can I help you?"
                        }
                    ]
                }
            ]
        },
        "parameters": {
            "vocabulary": {"John Smith": 5, "Jane Doe": 5}
        }
    }

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://.

Importante

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.

contextarray(object)(Opcional)

Lista de mensagens que fornecem contexto opcional de conversa para melhorar a precisão do reconhecimento.

ImportanteO SDK ainda não oferece suporte a este recurso.

ImportanteO aprimoramento de contexto melhora a precisão do reconhecimento de termos específicos de domínio. Para uso, consulte Context enhancement.

Restrições: Mensagens de contexto dos tipos input_text e text são limitadas a 5 mensagens cada. Se você exceder esse limite, apenas as 5 mais recentes serão mantidas. O comprimento total do texto por turno de contexto (comprimento combinado dos campos text para user e assistant) não deve exceder 400 caracteres (contagem caractere a caractere). Qualquer excesso será truncado a partir do final.

ImportanteAo incluir contexto, a ordem das mensagens em messages é importante: organize as mensagens de contexto por turno de conversa. Dentro de cada turno, a mensagem de user (tipo input_text) deve vir antes da mensagem correspondente de assistant (tipo text). Coloque uma mensagem de user que contenha input_audio por último no array messages.

Propriedades

rolestring(Obrigatório)

Função da mensagem. Valores válidos:

user: resultados de reconhecimento de turnos anteriores ou lista de palavras específicas de domínio.
assistant: respostas do modelo de linguagem grande de turnos anteriores.

contentarray(object)(Obrigatório)

Lista de itens de conteúdo da mensagem.

Propriedades

typestring(Obrigatório)

Tipo de conteúdo. Valores válidos:

input_text (opcional, contexto): resultados de reconhecimento da fala do usuário de turnos anteriores ou lista de palavras específicas de domínio (função user). Passe também o campo text.
text (opcional, contexto): respostas do modelo de linguagem grande de turnos anteriores (função assistant). Passe também o campo text.

textstring(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.

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

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.

ImportanteApenas qwen-audio-3.0-asr-flash-filetrans aceita hotwords inline.

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.

ImportanteCada 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)

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.

ObservaçãoCom 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)

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

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

qwen-audio-3.0-asr-flash-filetrans, fun-asr, fun-asr-2025-11-07, fun-asr-mtl, fun-asr-mtl-2025-08-25:
- 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
fun-asr-2025-08-25:
- zh: Chinês
- en: Inglês

Corpo da resposta

{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}

request_idstring

Identificador exclusivo desta chamada.

outputobject

Dados retornados pela interface de envio de tarefa.

Propriedades

task_idstring

ID da tarefa. Passe este ID como string na Query task interface.

task_statusstring

Status 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

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)

ImportanteEste 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

Exemplo de sucesso

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

Exemplo de erro

{
        "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": "FILE_DOWNLOAD_FAILED",
                "message": "FILE_DOWNLOAD_FAILED",
                "subtask_status": "FAILED"
            }
        ],
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 0,
            "FAILED": 1
        }
    }

request_idstring

Identificador exclusivo desta chamada.

outputobject

Dados retornados pela interface de consulta de tarefa.

Propriedades

task_idstring

ID da tarefa consultada.

task_statusstring

Status da tarefa consultada.

ObservaçãoQuando 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_timestring

Horário em que a tarefa foi enviada.

scheduled_timestring

Horário em que a tarefa foi agendada para execução.

end_timestring

Horário em que a tarefa terminou.

resultsarray[object]

Lista de resultados das subtarefas, um para cada arquivo de áudio a ser reconhecido.

Propriedades

subtask_statusstring

Status da subtarefa.

file_urlstring

URL do arquivo processado pela tarefa de transcrição.

transcription_urlstring

Link 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

ImportanteRetornado apenas quando a subtarefa falha.

Código de erro da subtarefa com falha.

messagestring

ImportanteRetornado apenas quando a subtarefa falha.

Mensagem de erro da subtarefa com falha.

task_metricsobject

Estatísticas gerais de execução da tarefa.

Propriedades

TOTALinteger

Número total de subtarefas.

SUCCEEDEDinteger

Número de subtarefas bem-sucedidas.

FAILEDinteger

Nú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

{
    "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â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.