Este tópico descreve os parâmetros e as interfaces do SDK em Python para reconhecimento de fala não em tempo real Qwen-Audio-ASR-Filetrans.
Para requisitos de entrada, como formatos de áudio suportados, limites de tamanho de arquivo e limites de duração, consulte Audio specifications.
Os exemplos a seguir usam o DashScope Python SDK 2.0. O Recurso principal (
O SDK usa a região de Pequim por padrão. Ao criar
As chaves de API variam entre regiões. Use a chave de API da região correspondente.
Defina os parâmetros da solicitação por meio de
O resultado do reconhecimento é salvo como um arquivo JSON.
Os seguintes parâmetros merecem atenção:
Crie um cliente com
Por padrão, uma tarefa com falha gera
Áudio codificado em Base64 não é suportado. Apenas áudio em uma URL publicamente acessível pode ser reconhecido. Fluxos binários e arquivos locais não podem ser reconhecidos diretamente.
As etapas típicas são as seguintes. Esta é uma abordagem; o processo exato varia conforme o product de armazenamento. Recomendamos que você upload the audio to Alibaba Cloud OSS:
Ao usar o SDK, se os arquivos de áudio estiverem armazenados no Alibaba Cloud OSS, URLs temporárias com o prefixo
Após o envio de uma tarefa, ela entra no estado de fila (PENDING). O tempo de espera depende do tamanho da fila e da duração do áudio, portanto não pode ser afirmado com exatidão, mas geralmente fica dentro de alguns minutos. Em geral, quanto mais longo o áudio, mais tempo leva.
Se você encontrar um erro de código, solucione o problema com base nas informações em Error codes.
Isso pode ser causado por limitação de taxa. Aguarde um momento e tente novamente.
Verifique se o formato de áudio e a taxa de amostragem estão corretos e atendem às restrições de parâmetros.
Use a ferramenta ffprobe para obter o contêiner de áudio, codec, taxa de amostragem, canais e outros detalhes:
Pré-requisitos
- Você ativou o service e Obtain an API key. Utilize Configure API key as an environment variable em vez de codificá-la diretamente no seu código para evitar riscos de segurança causados por vazamento de código.
- Install the latest DashScope SDK.
Início rápido
Os exemplos a seguir usam o DashScope Python SDK 2.0. O Recurso principal (client.audio.asr) fornece métodos para enviar, aguardar e consultar tarefas das duas maneiras a seguir:
- Envie a tarefa de forma assíncrona e aguarde sincronamente: após enviar a tarefa, bloqueie a thread atual até que a tarefa termine e retorne o resultado do reconhecimento.
- Envie a tarefa de forma assíncrona e consulte o resultado de forma assíncrona: após enviar a tarefa, chame a interface de consulta para recuperar o resultado sempre que necessário.
- Enviar de forma assíncrona e aguardar sincronamente
- Enviar de forma assíncrona e consultar o resultado de forma assíncrona

-
Chame
client.audio.asr.jobs.createpara enviar uma tarefa com os parâmetros da solicitação.- O service de transcrição de arquivos processa tarefas enviadas por meio da API com base no melhor esforço. Após o envio, a tarefa entra no estado de fila (
PENDING). O tempo de espera depende do tamanho da fila e da duração do arquivo, portanto não pode ser definido com precisão, mas geralmente fica dentro de alguns minutos. Assim que o processamento começa, o reconhecimento de fala é concluído a uma velocidade centenas de vezes superior ao tempo real. - Após a conclusão de cada tarefa, o resultado do reconhecimento e a URL de download permanecem válidos por 24 horas. Depois que expiram, não é mais possível consultar a tarefa ou baixar o resultado por meio da URL retornada em uma consulta anterior.
- O service de transcrição de arquivos processa tarefas enviadas por meio da API com base no melhor esforço. Após o envio, a tarefa entra no estado de fila (
-
Chame
client.audio.asr.jobs.wait(job=job)para aguardar a conclusão de forma síncrona. Enquanto a tarefa estiver emPENDINGouRUNNING,jobs.waitcontinua aguardando. Retorna umJobquando a tarefa é bem-sucedida. Os métodos retornam umJob. Leia a lista de resultados emjob.results; cadatranscription_urlaponta para um resultado de transcrição para download.
Endpoints do service
O SDK usa a região de Pequim por padrão. Ao criar dashscope.Client, defina a região em region e o ID do workspace em workspace. A configuração de região se aplica apenas a esse Client.
- Singapore
- China (Beijing)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Substitua {WorkspaceId} pelo seu Workspace ID real.Parâmetros de solicitação
Defina os parâmetros da solicitação por meio de client.audio.asr.transcribe ou client.audio.asr.jobs.create.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | str | Sim | O nome do modelo. |
file_urls | list[str] | Sim | Uma lista de URLs dos arquivos de áudio ou vídeo a serem transcritos. HTTP e HTTPS são suportados. Uma única solicitação suporta apenas uma URL. Para requisitos de entrada, como formatos de áudio suportados, limites de tamanho de arquivo e limites de duração, consulte Audio specifications.Se a gravação estiver armazenada no Alibaba Cloud OSS, a API RESTful suporta URLs temporárias com o prefixo oss://, enquanto o SDK não suporta URLs temporárias com o prefixo oss://. |
parameters.keep_dialect | bool | Não | Compatível apenas com qwen-audio-3.1-asr-flash-filetrans. O padrão é false, que transcreve dialetos para mandarim padrão. Defina como true para preservar as expressões dialetais. |
parameters.vocabulary_id | str | Não | O ID de uma lista de palavras-chave pré-compilada.Gere esse ID antecipadamente chamando a API de criação de lista de palavras-chave. Passe o ID durante o reconhecimento para usar as palavras-chave da lista.Indicado para cenários onde o vocabulário é conhecido e relativamente estável, e onde você precisa reutilizar a mesma lista de palavras entre solicitações.Para detalhes de uso, consulte Precompiled hotwords. |
parameters.vocabulary | dict | Não | Palavras-chave instantâneas.Passadas como pares chave-valor, onde a chave é o texto da palavra-chave (string) e o valor é o peso da palavra-chave (integer). Não é necessário criar uma lista de palavras-chave antecipadamente. O peso varia de [1, 5] ou é definido como 50: um valor em [1, 5] torna o modelo mais propenso a gerar a palavra à medida que o valor aumenta; um valor de 50 designa uma super palavra-chave, o que melhora muito a recuperação, mas o número de super palavras-chave não pode exceder 50.Adequado para otimização temporária de palavras-chave no nível de sessão.Quando as hotwords instantâneas e pré-compiladas são configuradas juntas, as duas listas são mescladas. Se a lista resultante exceder 2000 hotwords, 2000 serão selecionadas aleatoriamente. Para detalhes de uso, consulte Instant hotwords.Exemplo:O exemplo a seguir reutiliza o client configurado com a região e o workspace em Início rápido. |
parameters.channel_id | list[int] | Não | O índice das faixas de áudio a serem reconhecidas em um arquivo de áudio com múltiplas faixas. 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]. |
parameters.special_word_filter | str | Não | As 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. |
parameters.diarization_enabled | bool | Não | Se deve ativar a diarização de falantes. Desativado por padrão.Aplica-se apenas a áudio mono. Áudio multicanal não suporta diarização de falantes.Quando ativado, o resultado do reconhecimento inclui um campo speaker_id que distingue diferentes falantes.Quando a diarização de falantes está 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. |
parameters.speaker_count | int | Não | Um 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 número de falantes é detectado automaticamente. 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. |
parameters.language_hints | list[str] | Não | Os códigos de idioma a serem reconhecidos. Se você não puder determinar o idioma antecipadamente, deixe-o indefinido e o modelo detectará o idioma automaticamente.Você pode definir até 4 valores. Se definir mais, apenas os 4 primeiros serão usados.
Clique para visualizar os códigos de idioma suportados
|
Resposta
Job
Job contém informações da tarefa, saída bruta e uso.
| Campo | Descrição |
|---|---|
task_id | O ID da tarefa. |
status | O status da tarefa: PENDING, RUNNING, SUCCEEDED ou FAILED. |
submitted_at | O horário de envio, correspondente a job.output["submit_time"]. |
scheduled_at | O início do processamento, correspondente a job.output["scheduled_time"]. |
finished_at | O horário de conclusão, correspondente a job.output["end_time"]. |
output | O dicionário de saída bruta da tarefa. |
results | A lista de resultados de subtarefas, acessível por job.results. Baixe o arquivo JSON em transcription_url para obter o texto reconhecido. |
usage | Informações de uso da tarefa. qwen-audio-3.1-asr-flash-filetrans informa o uso de Tokens em input_tokens, output_tokens e total_tokens. qwen-audio-3.0-asr-flash-filetrans é medido por duration. |
Job.output
job.output é o dicionário de saída bruta da tarefa retornado pelo serviço.
- PENDING
- RUNNING
- SUCCEEDED
- FAILED (raise_on_error=False)
| Parâmetro | Descrição |
|---|---|
code | O código de erro. Combine-o com o campo message e consulte Error codes para solucionar o problema. |
message | A mensagem de erro. Combine-a com o campo code e consulte Error codes para solucionar o problema. |
task_id | ID da tarefa. |
task_status | Status da tarefa.Um dos quatro estados: PENDING, RUNNING, SUCCEEDED e FAILED.Quando uma tarefa contém várias 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 cada subtarefa. |
results | Resultados do reconhecimento das subtarefas. |
subtask_status | Status da subtarefa.Um dos quatro estados: PENDING, RUNNING, SUCCEEDED e FAILED. |
file_url | URL do áudio reconhecido. |
transcription_url | URL do resultado do reconhecimento de áudio.O resultado do reconhecimento é salvo como um arquivo JSON. Você pode baixar o arquivo pelo link associado a transcription_url ou ler seu conteúdo diretamente por meio de uma solicitação HTTP. Para o conteúdo do arquivo JSON, consulte Recognition result description. |
Descrição do resultado do reconhecimento
O resultado do reconhecimento é salvo como um arquivo JSON.
| Parâmetro | Tipo | Descrição |
|---|---|---|
audio_format | string | O formato de áudio do arquivo de origem. |
channels | array[integer] | O índice da faixa de áudio no arquivo de origem. Para áudio de faixa única, [0] é retornado; para áudio de duas faixas, [0, 1] é retornado; e assim por diante. |
original_sampling_rate | integer | A taxa de amostragem (Hz) do áudio no arquivo de origem. |
original_duration_in_milliseconds | integer | A duração original do áudio (ms) no arquivo de origem. |
channel_id | integer | O índice da faixa do resultado da transcrição, começando em 0. |
content_duration | integer | A duração (ms) do conteúdo na faixa identificado como fala. A descrição de cobrança a seguir se aplica a qwen-audio-3.0-asr-flash-filetrans. qwen-audio-3.1-asr-flash-filetrans é cobrado pelo uso de tokens. |
transcript | string | O resultado da transcrição no nível de parágrafo. |
sentences | array | O resultado da transcrição no nível de sentença. |
words | array | O resultado da transcrição no nível de palavra. |
begin_time | integer | O carimbo de data/hora inicial (ms). |
end_time | integer | O carimbo de data/hora final (ms). |
text | string | O resultado da transcrição. |
speaker_id | integer | O í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 | A pontuação prevista após a palavra, se houver. |
Interfaces principais
Recurso principal (client.audio.asr)
Crie um cliente com dashscope.Client e use o recurso client.audio.asr. Todos os métodos abaixo retornam um Job.
| Método | Assinatura do método | Descrição |
|---|---|---|
transcribe | Envie uma tarefa e aguarde a conclusão de forma síncrona. O modelo padrão é qwen-audio-3.1-asr-flash-filetrans. Especifique model explicitamente para chamar outro modelo. | |
jobs.create | Envie uma tarefa e retorne um Job com task_id e status, sem aguardar a conclusão do reconhecimento. | |
jobs.wait | Passe um Job ou ID de tarefa e aguarde a conclusão de forma síncrona. Defina os intervalos inicial e máximo de consulta com poll_interval e max_interval, e o tempo total de espera com timeout. Todos os valores são em segundos. | |
jobs.fetch | Consulte o status e os resultados da tarefa uma vez por ID, sem aguardar a conclusão. |
Códigos de erro
Por padrão, uma tarefa com falha gera DashScopeError. Para receber um Job com falha, defina raise_on_error=False ao criar o Client e verifique job.status.
Se você encontrar um erro, consulte Error codes para solucionar o problema.
Quando uma tarefa contém várias subtarefas, o status geral da tarefa é marcado como SUCCEEDED desde que pelo menos uma subtarefa tenha sucesso. Verifique o campo subtask_status para determinar o resultado de cada subtarefa.
Exemplo de resposta de erro:
FAQ
Recursos
P: Áudio codificado em Base64 é suportado?
Áudio codificado em Base64 não é suportado. Apenas áudio em uma URL publicamente acessível pode ser reconhecido. Fluxos binários e arquivos locais não podem ser reconhecidos diretamente.
P: Como torno um arquivo de áudio disponível em uma URL publicamente acessível?
As etapas típicas são as seguintes. Esta é uma abordagem; o processo exato varia conforme o product de armazenamento. Recomendamos que você upload the audio to Alibaba Cloud OSS:
1. Escolha um método de armazenamento e hospedagem
1. Escolha um método de armazenamento e hospedagem
Por exemplo:
-
Service de armazenamento de objetos (recomendado):
- Use o service de armazenamento de objetos de um provedor de cloud (como Alibaba Cloud OSS) para fazer upload do arquivo de áudio para um bucket e defini-lo como acesso público.
- Vantagens: alta disponibilidade, suporte a aceleração CDN e gerenciamento fácil.
-
Servidor web:
- Coloque o arquivo de áudio em um servidor web que suporte acesso HTTP/HTTPS (como Nginx ou Apache).
- Vantagens: adequado para pequenos projetos ou testes locais.
-
Rede de distribuição de conteúdo (CDN):
- Hospede o arquivo de áudio em uma CDN e acesse-o por meio da URL fornecida pela CDN.
- Vantagens: acelera a entrega de arquivos e atende a cenários de alta concorrência.
2. Faça upload do arquivo de áudio
2. Faça upload do arquivo de áudio
Faça upload do áudio de acordo com o método de armazenamento ou hospedagem escolhido. Por exemplo:
-
Service de armazenamento de objetos:
- Faça login no console do provedor de cloud e crie um bucket.
- Faça upload do arquivo de áudio e defina sua permissão como leitura pública ou gere um link de acesso temporário.
-
Servidor web:
- Coloque o arquivo de áudio em um diretório designado no servidor (como
/var/www/html/audio/). - Certifique-se de que o arquivo esteja acessível via HTTP/HTTPS.
- Coloque o arquivo de áudio em um diretório designado no servidor (como
3. Gere uma URL publicamente acessível
3. Gere uma URL publicamente acessível
Por exemplo:
-
Service de armazenamento de objetos:
- Após o upload do arquivo, o sistema gera automaticamente uma URL de acesso público (geralmente no formato
https://<bucket-name>.<region>.aliyuncs.com/<file-name>). - Para um nome de domínio mais amigável, vincule um domínio personalizado e ative HTTPS.
- Após o upload do arquivo, o sistema gera automaticamente uma URL de acesso público (geralmente no formato
-
Servidor web:
- A URL de acesso geralmente é o endereço do servidor mais o caminho do arquivo (como
https://your-domain.com/audio/file.mp3).
- A URL de acesso geralmente é o endereço do servidor mais o caminho do arquivo (como
-
CDN:
- Após configurar a aceleração CDN, use a URL fornecida pela CDN (como
https://cdn.your-domain.com/audio/file.mp3).
- Após configurar a aceleração CDN, use a URL fornecida pela CDN (como
4. Verifique se a URL funciona
4. Verifique se a URL funciona
Certifique-se de que a URL gerada esteja acessível pela rede pública. Por exemplo:
- Abra a URL em um navegador e verifique se o arquivo de áudio é reproduzido.
- Use uma ferramenta (como
curlou Postman) para verificar se a URL retorna a resposta HTTP correta (código de status 200).
oss:// não são suportadas.
Ao usar a API RESTful, se os arquivos de áudio estiverem armazenados no Alibaba Cloud OSS, URLs temporárias com o prefixo oss:// são suportadas:
- A URL temporária é válida por 48 horas e não pode ser usada após a expiração. Não a utilize em ambiente de produção.
- A API para obtenção de credencial de upload tem limite de 100 QPS e não suporta scale out. Não a utilize em ambientes de produção, cenários de alta concorrência ou cenários de teste de estresse.
- Para ambientes de produção, use um service de armazenamento estável, como OSS, para garantir a disponibilidade de arquivos a longo prazo e evitar problemas de limitação de taxa.
