Skip to main content

SDK Python de reconhecimento de fala não em tempo real do Qwen-Audio-ASR-Filetrans

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.

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
Enviar uma tarefa e aguardar
  1. Chame client.audio.asr.jobs.create para 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.
  2. Chame client.audio.asr.jobs.wait(job=job) para aguardar a conclusão de forma síncrona. Enquanto a tarefa estiver em PENDING ou RUNNING, jobs.wait continua aguardando. Retorna um Job quando a tarefa é bem-sucedida. Os métodos retornam um Job. Leia a lista de resultados em job.results; cada transcription_url aponta para um resultado de transcrição para download.
import json
import os

import dashscope

# Substitua {WorkspaceId} pelo ID real do workspace da região.
client = dashscope.Client(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

job = client.audio.asr.jobs.create(
    model="qwen-audio-3.0-asr-flash-filetrans",
    file_urls=["{YOUR_AUDIO_URL}"],
)

job = client.audio.asr.jobs.wait(job=job)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))

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.
As chaves de API variam entre regiões. Use a chave de API da região correspondente.

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âmetroTipoObrigatórioDescrição
modelstrSimO nome do modelo.
file_urlslist[str]SimUma 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://.
  • Uma URL temporária é válida por 48 horas e não pode ser usada após a expiração. 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 produção, cenários de alta concorrência ou testes de carga.
  • Para ambientes de 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 uma 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 suporta a configuração de cabeçalhos de solicitação.
parameters.keep_dialectboolNãoCompatí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_idstrNãoO 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.vocabularydictNãoPalavras-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.
vocab = {"Zhang San": 5, "Li Si": 5}
result = client.audio.asr.jobs.create(
    model="qwen-audio-3.0-asr-flash-filetrans",
    file_urls=["{YOUR_AUDIO_URL}"],
    parameters={"vocabulary": vocab},
)
parameters.channel_idlist[int]NãoO í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.
Cada faixa especificada é faturada independentemente. Por exemplo, solicitar [0, 1] para um único arquivo incorre em duas cobranças separadas.
Valor padrão: [0].
parameters.special_word_filterstrNãoAs 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_enabledboolNãoSe 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.
Valor padrão: False.Para um exemplo de speaker_id, consulte Recognition result description.
parameters.speaker_countintNão
Entra em vigor apenas quando a diarização de falantes está ativada (diarization_enabled definido como True).
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_hintslist[str]NãoOs 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.
  • 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

Resposta

Job

Job contém informações da tarefa, saída bruta e uso.
{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "status": "PENDING",
    "submitted_at": "2026-10-29 10:00:00.000",
    "scheduled_at": null,
    "finished_at": null,
    "output": {
        "task_id": "00000000-0000-0000-0000-000000000001",
        "task_status": "PENDING",
        "submit_time": "2026-10-29 10:00:00.000"
    },
    "usage": null
}
CampoDescrição
task_idO ID da tarefa.
statusO status da tarefa: PENDING, RUNNING, SUCCEEDED ou FAILED.
submitted_atO horário de envio, correspondente a job.output["submit_time"].
scheduled_atO início do processamento, correspondente a job.output["scheduled_time"].
finished_atO horário de conclusão, correspondente a job.output["end_time"].
outputO dicionário de saída bruta da tarefa.
resultsA lista de resultados de subtarefas, acessível por job.results. Baixe o arquivo JSON em transcription_url para obter o texto reconhecido.
usageInformaçõ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)
{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "task_status": "PENDING",
    "submit_time": "2026-10-29 10:00:00.000"
}
ParâmetroDescrição
codeO código de erro. Combine-o com o campo message e consulte Error codes para solucionar o problema.
messageA mensagem de erro. Combine-a com o campo code e consulte Error codes para solucionar o problema.
task_idID da tarefa.
task_statusStatus 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.
resultsResultados do reconhecimento das subtarefas.
subtask_statusStatus da subtarefa.Um dos quatro estados: PENDING, RUNNING, SUCCEEDED e FAILED.
file_urlURL do áudio reconhecido.
transcription_urlURL 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.
{
    "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_formatstringO formato de áudio do arquivo de origem.
channelsarray[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_rateintegerA taxa de amostragem (Hz) do áudio no arquivo de origem.
original_duration_in_millisecondsintegerA duração original do áudio (ms) no arquivo de origem.
channel_idintegerO índice da faixa do resultado da transcrição, começando em 0.
content_durationintegerA 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.
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.
transcriptstringO resultado da transcrição no nível de parágrafo.
sentencesarrayO resultado da transcrição no nível de sentença.
wordsarrayO resultado da transcrição no nível de palavra.
begin_timeintegerO carimbo de data/hora inicial (ms).
end_timeintegerO carimbo de data/hora final (ms).
textstringO resultado da transcrição.
speaker_idintegerO í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.
punctuationstringA 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étodoAssinatura do métodoDescrição
transcribe
def transcribe(
    file_urls: List[str],
    *,
    model: str = "qwen-audio-3.1-asr-flash-filetrans",
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: float = 86400.0,
    submit_timeout: Optional[float] = None,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
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
def create(
    *,
    model: str,
    file_urls: List[str],
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
Envie uma tarefa e retorne um Job com task_id e status, sem aguardar a conclusão do reconhecimento.
jobs.wait
def wait(
    job: Union[Job, str],
    *,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    timeout: float = 86400.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
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
def fetch(
    task_id: str,
    *,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
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:
{
    "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": "InvalidFile.DownloadFailed",
            "message": "The audio file cannot be downloaded.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

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:
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.
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.
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.
  • 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).
  • CDN:
    • Após configurar a aceleração CDN, use a URL fornecida pela CDN (como https://cdn.your-domain.com/audio/file.mp3).
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 curl ou Postman) para verificar se a URL retorna a resposta HTTP correta (código de status 200).
Ao usar o SDK, se os arquivos de áudio estiverem armazenados no Alibaba Cloud OSS, URLs temporárias com o prefixo 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.

P: Quanto tempo leva para obter o resultado do reconhecimento?

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.

Solução de problemas

Se você encontrar um erro de código, solucione o problema com base nas informações em Error codes.

P: A sondagem nunca retorna um resultado?

Isso pode ser causado por limitação de taxa. Aguarde um momento e tente novamente.

P: Por que a fala não pode ser reconhecida (sem resultado de reconhecimento)?

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:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx