Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Non-real-time speech recognition

Última atualização: Oct 30, 2026

Os modelos de reconhecimento de fala não em tempo real convertem áudio gravado em texto. Eles oferecem suporte a reconhecimento multilíngue, reconhecimento de canto, rejeição de ruído e diarização de falantes, o que os torna adequados para transcrição de reuniões, análise de chamadas, geração de legendas e cenários semelhantes.

Visão geral

Transcreva arquivos de áudio e vídeo gravados em lotes por meio de tarefas assíncronas.

  • O aprimoramento de contexto melhora a precisão do reconhecimento por meio de um contexto configurável.
  • Palavras-chave personalizadas aumentam a precisão no reconhecimento de nomes próprios usando uma lista de palavras predefinida.
  • Os recursos configuráveis incluem diarização de falantes, filtragem de palavras sensíveis e carimbos de data/hora no nível da frase ou da palavra.
  • A transcrição assíncrona aceita um único arquivo de áudio com duração de até 12 horas e tamanho máximo de 2 GB.
  • Há suporte para qualquer taxa de amostragem, além de formatos de áudio e vídeo populares como AAC, WAV e MP3.

Para cenários em tempo real, como legendas ao vivo, reuniões online e assistentes de voz, use Real-time speech recognition. Para obter orientações sobre a escolha do modelo, consulte Speech-to-text.

Pré-requisitos

Início rápido

ImportanteOs exemplos a seguir usam qwen-audio-3.1-asr-flash-filetrans e qwen-audio-3.1-asr-flash. O primeiro utiliza chamadas assíncronas: defina X-DashScope-Async: enable ao enviar a solicitação e consulte o resultado da tarefa. O segundo utiliza chamadas síncronas e oferece saída com ou sem streaming.

Se você chamar uma implantação dedicada do service de modelo e receber o erro current user api does not support asynchronous calls, significa que a implantação suporta apenas chamadas síncronas. Altere o cabeçalho da requisição para X-DashScope-Async: disable e mantenha o restante da chamada inalterado.

Qwen-Audio-ASR-Filetrans

Como os arquivos de áudio e vídeo podem ser grandes, a API de transcrição de arquivos utiliza chamadas assíncronas: envie uma tarefa, faça polling na API de consulta para verificar seu status e recupere o resultado do reconhecimento após a conclusão da tarefa.

cURL

Ao chamar a API com cURL, primeiro envie a tarefa para obter um task_id e, em seguida, consulte o resultado da tarefa usando esse ID.

Enviar uma tarefa

A configuração a seguir destina-se à região Singapore. Substitua {WorkspaceId} pelo seu Workspace ID real. A configuração varia conforme a região.

curl -X POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-Async: enable" \
-d '{
    "model": "qwen-audio-3.1-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "channel_id": [0],
        "language_hints": ["zh", "en"]
    }
}'

Obter o resultado da tarefa

Esta API de consulta permite 20 QPS por padrão e pode escalar até 100 QPS. Para uma frequência maior ou para evitar limitações causadas pelo polling, configure um callback de tarefa assíncrona (consulte High-concurrency scenarios: use callbacks instead of polling).

A configuração a seguir destina-se à região Singapore. Substitua {WorkspaceId} pelo seu Workspace ID real. A configuração varia conforme a região.

curl -X GET 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json"

Baixar o resultado do reconhecimento

Após o sucesso da tarefa, o campo output.results[].transcription_url retornado pela API de consulta aponta para um arquivo JSON publicamente baixável que contém o resultado completo do reconhecimento. Essa URL é válida por 24 horas por padrão; portanto, baixe e salve o arquivo prontamente.

# Replace {transcription_url} with the transcription_url value returned by the query API
curl -sS '{transcription_url}' -o transcription.json
cat transcription.json | jq .

Python

from http import HTTPStatus
from dashscope.audio.asr import Transcription
from urllib import request
import dashscope
import os
import json

# The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

task_response = Transcription.async_call(
    model='qwen-audio-3.1-asr-flash-filetrans',
    file_urls=['{YOUR_AUDIO_URL}'],
    language_hints=['zh', 'en']  # language_hints is an optional parameter used to specify the language codes of the audio to be recognized. For the value range, see the API reference documentation.
)

transcription_response = Transcription.wait(task=task_response.output.task_id)

if transcription_response.status_code == HTTPStatus.OK:
    for transcription in transcription_response.output['results']:
        if transcription['subtask_status'] == 'SUCCEEDED':
            url = transcription['transcription_url']
            result = json.loads(request.urlopen(url).read().decode('utf8'))
            print(json.dumps(result, indent=4,
                            ensure_ascii=False))
        else:
            print('transcription failed!')
            print(transcription)
else:
    print('Error: ', transcription_response.output.message)

Java

import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.*;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Arrays;
import java.util.List;

public class Main {
    public static void main(String[] args) {
        // The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        // Create the transcription request parameters.
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
                        // If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: .apiKey("sk-xxx")
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .model("qwen-audio-3.1-asr-flash-filetrans")
                        // language_hints is an optional parameter used to specify the language codes of the audio to be recognized. For the value range, see the API reference documentation.
                        .parameter("language_hints", new String[]{"zh", "en"})
                        .fileUrls(
                                Arrays.asList(
                                        "{YOUR_AUDIO_URL}"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // Submit the transcription request
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // Check whether the task was submitted successfully
            if (result.getTaskId() == null) {
                System.out.println("Error: " + result.getOutput());
                System.exit(1);
            }
            // Block and wait for the task to complete and get the result
            result = transcription.wait(
                    TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
            // Get the transcription result
            List<TranscriptionTaskResult> taskResultList = result.getResults();
            if (taskResultList != null && taskResultList.size() > 0) {
                for (TranscriptionTaskResult taskResult : taskResultList) {
                    String transcriptionUrl = taskResult.getTranscriptionUrl();
                    HttpURLConnection connection =
                            (HttpURLConnection) new URL(transcriptionUrl).openConnection();
                    connection.setRequestMethod("GET");
                    connection.connect();
                    BufferedReader reader =
                            new BufferedReader(new InputStreamReader(connection.getInputStream()));
                    Gson gson = new GsonBuilder().setPrettyPrinting().create();
                    JsonElement jsonResult = gson.fromJson(reader, JsonObject.class);
                    System.out.println(gson.toJson(jsonResult));
                }
            }
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

O resultado completo do reconhecimento é impresso no console em formato JSON. Ele contém o texto transcrito juntamente com os tempos de início e fim de cada segmento no arquivo de áudio ou vídeo, em milissegundos.

  • 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": 2480,
            "text": "Hello World, this is the Alibaba Speech Lab.",
            "sentences": [
                {
                    "begin_time": 760,
                    "end_time": 3240,
                    "text": "Hello World, this is the Alibaba Speech Lab.",
                    "sentence_id": 1,
                    "words": [
                        {
                            "begin_time": 760,
                            "end_time": 1000,
                            "text": "Hello",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 1000,
                            "end_time": 1120,
                            "text": " World",
                            "punctuation": ","
                        },
                        {
                            "begin_time": 1400,
                            "end_time": 1920,
                            "text": "this is",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 1920,
                            "end_time": 2520,
                            "text": "the Alibaba",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 2520,
                            "end_time": 2840,
                            "text": "Speech",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 2840,
                            "end_time": 3240,
                            "text": "Lab",
                            "punctuation": "."
                        }
                    ]
                }
            ]
        }
    ]
}

Qwen-Audio-ASR

A série Qwen-Audio-ASR utiliza chamadas síncronas para arquivos de áudio de até 5 minutos e oferece resultados com ou sem streaming.

A configuração a seguir destina-se à região Singapore. Substitua {WorkspaceId} pelo seu Workspace ID real. A configuração varia conforme a região. A chave de API para a região Singapore difere daquela usada na região Beijing.

curl --location --request POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-SSE: disable" \
     --data '{
    "model": "qwen-audio-3.1-asr-flash",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "{YOUR_AUDIO_URL}"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000"
    }
}'

ImportanteA resposta HTTP de qwen-audio-3.1-asr-flash não contém o campo choices. O resultado do reconhecimento tem a seguinte estrutura:

{
  "output": {
    "sentence": {
      "text": "Recognized text content"
    },
    "text": "Recognized text content"
  },
  "request_id": "..."
}

O texto reconhecido está disponível em output.sentence.text e output.text.

Recursos avançados

Processamento de arquivos de áudio longos

O reconhecimento de fala não em tempo real permite a transcrição assíncrona de arquivos de áudio longos. Esse recurso é ideal para cenários como atas de reuniões, transcrições de entrevistas e reprodução de chamadas.

Limitações:
  • Qwen-Audio-ASR-Filetrans/Fun-ASR / Qwen3-ASR-Filetrans / Paraformer: um único arquivo de áudio pode ter até 2 GB de tamanho e 12 horas de duração.
  • Qwen-Audio-ASR / Fun-ASR-Flash: um único arquivo de áudio pode ter até 2 GB de tamanho e 5 minutos de duração.
  • Qwen3-ASR-Flash: um único arquivo de áudio pode ter até 10 MB de tamanho e 5 minutos de duração. Para áudios mais longos, utilize Qwen-Audio-ASR-Filetrans.
  • Com diarização de falantes ativada: mantenha a duração do áudio dentro de 2 horas. Áudios mais longos podem causar falhas no reconhecimento ou timeouts. Para mais informações, consulte Speaker diarization.

Fluxo de chamada: a transcrição de áudio longo utiliza um modelo de tarefa assíncrona com três etapas:

  1. Envie a tarefa de transcrição e obtenha um task_id.
  2. Consulte periodicamente a API de status da tarefa ou use o método de espera do SDK para bloquear a execução até que a tarefa seja concluída.
  3. Após a conclusão da tarefa, baixe o JSON com o resultado do reconhecimento a partir da URL retornada.

Para exemplos de código, consulte o código Quick start em Reconhecimento de fala não em tempo real.

Saída em streaming

Os modelos Qwen-Audio-ASR/Fun-ASR-Flash/Qwen3-ASR-Flash suportam saída em streaming, retornando resultados intermediários à medida que o reconhecimento avança. Essa abordagem atende bem a cenários que exigem feedback de progresso em tempo real. Para o formato de solicitação e resposta HTTP SSE do Qwen-Audio-ASR e do Fun-ASR-Flash, consulte Qwen-Audio-ASR HTTP API e Fun-ASR-Flash HTTP API.

Modelos de transcrição assíncrona, como Qwen-Audio-ASR-Filetrans, Fun-ASR, Qwen3-ASR-Filetrans e Paraformer, não oferecem suporte a saída em streaming. Obtenha o resultado final consultando a tarefa periodicamente (para mais detalhes, consulte Process long audio files).

Como ativar:
  • DashScope Python SDK: defina o parâmetro stream como True.
  • DashScope Java SDK: chame a API streamCall.
  • DashScope HTTP: defina o cabeçalho X-DashScope-SSE como enable.

Melhoria de precisão com hotwords

Hotwords aumentam a precisão do reconhecimento de substantivos próprios específicos de domínio, como nomes de pessoas, locais e produtos. Para detalhes sobre como criar e usar hotwords, consulte Improve recognition accuracy.

Cada SDK adota convenções de nomenclatura diferentes para esses parâmetros, como chaves de dicionário, propriedades de objeto ou métodos. Para o mapeamento completo dos campos, consulte a referência da API de cada SDK.

Melhoria de precisão com aprimoramento de contexto

O aprimoramento de contexto envia o histórico da conversa para o modelo ASR, o que melhora significativamente a precisão da transcrição de substantivos próprios. Para detalhes sobre como usar esse recurso e ver exemplos de resultados, consulte Context enhancement.

Diarização de falantes

Para ativar a diarização de falantes com qwen-audio-3.1-asr-flash, use speaker_diarization_enabled. Para os parâmetros e a estrutura da resposta, consulte HTTP API.

A diarização de falantes identifica automaticamente os diferentes interlocutores no áudio e rotula cada frase no resultado da transcrição com uma tag de falante. Esse recurso é adequado para cenários como reuniões com múltiplos participantes e gravações de entrevistas.

A configuração e os exemplos a seguir se aplicam a: modelos das séries Qwen-Audio-ASR-Filetrans, Fun-ASR e Paraformer.

Como ativar: defina o parâmetro diarization_enabled como true na requisição da API. No resultado, cada frase inclui um campo speaker_id que identifica o falante.

Exemplo de estrutura de retorno (trecho):

{
  "transcripts": [
    {
      "sentences": [
        { "begin_time": 100, "end_time": 3820, "text": "Hello, let's discuss the project progress today.", "speaker_id": 0 },
        { "begin_time": 3820, "end_time": 6500, "text": "Sure, let me give a quick report first.", "speaker_id": 1 }
      ]
    }
  ]
}

Os SDKs utilizam convenções de nomenclatura distintas para esses campos, como chaves de dicionário, propriedades de objeto ou métodos. Para o mapeamento completo dos campos, consulte a referência da API de cada SDK.

ImportanteAo ativar a diarização de falantes, mantenha a duração do áudio dentro de 2 horas. Áudios mais longos podem causar falhas no reconhecimento ou timeouts. Para os limites de duração de áudio com a diarização desativada, consulte Process long audio files. A diarização de falantes suporta apenas áudio mono.

Para as definições completas dos campos, consulte a referência da API.

Filtragem de palavras sensíveis

A filtragem de palavras sensíveis substitui ou remove termos sensíveis no resultado do reconhecimento. Essa funcionalidade é útil para cenários como inspeção de qualidade de atendimento ao cliente, conformidade de conteúdo e moderação de legendas.

Modelos suportados: séries Qwen-Audio-ASR-Filetrans, Fun-ASR e Paraformer.

Comportamento padrão: quando o parâmetro special_word_filter não é fornecido, o sistema utiliza a lista de palavras sensíveis do Model Studio integrada. As palavras correspondentes são substituídas por uma string de * de igual comprimento.

Configuração personalizada: special_word_filter é um objeto JSON com três subcampos:

  • filter_with_signed.word_list: um array de strings com palavras sensíveis a serem substituídas por uma sequência de * de igual comprimento. Por exemplo, com ["test"], "Please help me test this" torna-se "Please help me **** this".
  • filter_with_empty.word_list: um array de strings com palavras sensíveis a serem removidas completamente do resultado. Por exemplo, com ["start"], "Is the game about to start now" torna-se "Is the game about to now".
  • system_reserved_filter: um valor booleano cujo padrão é true. Ele controla se a lista de palavras sensíveis integrada do sistema também deve ser aplicada, funcionando em conjunto com sua lista personalizada.

Exemplo de configuração:

{
  "special_word_filter": {
    "filter_with_signed": {
      "word_list": ["test"]
    },
    "filter_with_empty": {
      "word_list": ["start", "happen"]
    },
    "system_reserved_filter": true
  }
}

Os SDKs adotam convenções de nomenclatura diferentes para esses parâmetros, como chaves de dicionário, propriedades de objeto ou métodos. Para o mapeamento completo dos campos, consulte a referência da API.

Obtenção de timestamps

O reconhecimento de fala não em tempo real pode gerar timestamps no resultado da transcrição, facilitando a geração de legendas, o destaque de palavras-chave e a edição de áudio/vídeo. Os modelos Qwen-Audio-ASR-Filetrans, Qwen-Audio-ASR, Fun-ASR, Fun-ASR-Flash, Qwen3-ASR-Filetrans e Paraformer suportam timestamps, mas o comportamento padrão e o método de controle variam conforme o modelo:

  • Qwen-Audio-ASR-Filetrans/Qwen-Audio-ASR/Fun-ASR/Fun-ASR-Flash/Paraformer: os timestamps estão permanentemente ativados e não podem ser desligados.
  • Qwen3-ASR-Filetrans: apenas a chamada assíncrona via DashScope suporta timestamps, que ficam permanentemente ativados. Utilize o parâmetro de requisição enable_words para controlar o nível de detalhe do timestamp: defina-o como false (padrão) para retornar timestamps no nível da frase, ou true para retornar timestamps no nível da palavra. Timestamps no nível da palavra suportam apenas os seguintes idiomas: chinês, inglês, japonês, coreano, alemão, francês, espanhol, italiano, português e russo. A precisão não é garantida para outros idiomas.

Os timestamps são expressos em milissegundos e retornados em dois níveis:

  • Nível da frase: sentences[].begin_time e sentences[].end_time marcam o início e o fim de cada frase no áudio.
  • Nível da palavra: o array sentences[].words[], onde cada elemento contém begin_time, end_time e text (o texto daquela palavra).

Exemplo de estrutura de retorno (trecho da API de tarefa assíncrona do DashScope):

{
  "transcripts": [{
    "sentences": [{
      "begin_time": 100,
      "end_time": 3820,
      "text": "Hello, let's discuss the project progress today.",
      "words": [
        { "begin_time": 100, "end_time": 596, "text": "Hello," },
        { "begin_time": 596, "end_time": 844, "text": "let's" }
      ]
    }]
  }]
}

ImportanteO timestamp dentro do áudio é um número inteiro em milissegundos (como 100). Não o confunda com o end_time no nível da tarefa (o horário de conclusão da tarefa, uma string de data como "2024-09-12 15:11:40.903"). São campos distintos.

Os SDKs utilizam convenções de nomenclatura distintas para esses campos, como chaves de dicionário, propriedades de objeto ou métodos. Para o mapeamento completo dos campos, consulte a referência da API.

Aplicação em produção

Ao implementar o reconhecimento de fala não em tempo real em produção, as práticas recomendadas a seguir ajudam a melhorar a qualidade do reconhecimento e a estabilidade do sistema.

Cenários de alta concorrência: use callbacks em vez de polling

Para tarefas de transcrição assíncrona (Qwen-Audio-ASR-Filetrans, Fun-ASR, Qwen3-ASR-Filetrans e Paraformer), você envia a tarefa através de POST /api/v1/services/audio/asr/transcription e geralmente obtém o resultado chamando periodicamente a API de consulta GET /api/v1/tasks/{task_id}. Essa API de consulta tem um padrão de 20 QPS, escalável até 100 QPS. Em cenários de lote com alta concorrência, o polling frequente aciona facilmente limitações de taxa.

Configure notificações de callback via EventBridge. Quando uma tarefa é concluída, o Model Studio envia automaticamente um evento dashscope:System:AsyncTaskFinish para o destino configurado (um endpoint HTTP/HTTPS ou um tópico RocketMQ). Após receber o evento, o consumidor não precisa mais chamar a API de consulta, evitando o risco de limitação por polling frequente. Para mais informações, consulte Configure EventBridge callback notifications.

Modelos suportados

  • Suportados: Qwen-Audio-ASR-Filetrans, Fun-ASR, Qwen3-ASR-Filetrans e Paraformer (todas as tarefas de transcrição assíncrona).
  • Não suportados: Qwen3-ASR-Flash (chamadas síncronas ou em streaming, que não são tarefas assíncronas).

Conteúdo da mensagem de callback

Para todos os três modelos, o corpo da mensagem de callback possui data.contain_result definido como true, e data.output_result carrega diretamente a transcription_url. Ao receber o callback, o consumidor pode obter o resultado do reconhecimento sem precisar chamar GET /api/v1/tasks/{task_id} novamente. No entanto, o caminho e a estrutura do campo de resultado diferem entre os três modelos. Consulte a tabela abaixo.

ObservaçãoAo desenvolver o consumidor, escolha o caminho correto para o modelo utilizado. Evite codificar um único caminho fixo. Em cenários de falha, data.output_result.output deixa de conter results/result; em vez disso, passa a conter os campos code e message. Verifique primeiro data.task_status antes de ler o resultado.

Modelo

Parâmetro de envio

Caminho do campo de resultado (baseado no corpo do callback)

Campo usage

Qwen-Audio-ASR-Filetrans, Fun-ASR

input.file_urls (array; apenas 1 URL por chamada)

data.output_result.output.results[ ].transcription_url (array, uma entrada por arquivo, com subtask_status; inclui também task_metrics)

duration

Paraformer

input.file_urls (array; apenas 1 URL por chamada)

Igual ao Qwen-Audio-ASR-Filetrans/Fun-ASR: data.output_result.output.results[ ].transcription_url

duration

Qwen3-ASR-Filetrans

input.file_url (objeto único; apenas 1 URL por chamada)

data.output_result.output.result.transcription_url (objeto único, sem results[ ] / task_metrics)

seconds

Notas de uso

Segurança (entrega HTTP/HTTPS): em produção, valide os campos de cabeçalho X-Eventbridge-Signature* na requisição de callback antes de consumi-la. Caso contrário, qualquer IP externo pode forjar um evento AsyncTaskFinish e injetar resultados falsos de reconhecimento. Defina também um timeout de recebimento de pelo menos 5 segundos no receptor. O método de entrega via RocketMQ não possui assinatura no nível da mensagem; sua segurança é garantida pelo mecanismo de autenticação do próprio RocketMQ.

Latência de entrega: desde a conclusão da tarefa (end_time) até o momento em que o destino da entrega (um endpoint HTTP/HTTPS ou um tópico RocketMQ) recebe a mensagem, o atraso costuma variar entre 1 e 90 segundos. A latência exata depende da carga em tempo real do EventBridge.

Idempotência: o mesmo evento pode ser entregue múltiplas vezes devido a retries. Implemente processamento idempotente no consumidor, utilizando CloudEvents data.id ou data.task_id como chave de deduplicação.

Recomendações para produção

  • Hospedagem de arquivos: carregue os arquivos de áudio no Alibaba Cloud OSS e chame a API via URL. Evite uploads de arquivos locais (chamadas com arquivos locais têm limite de 100 QPS e não podem ser escaladas).
  • Polling assíncrono: a transcrição de áudio longo utiliza um modelo assíncrono. Defina um intervalo de polling razoável (como 2 a 5 segundos) para evitar consultas frequentes que consomem sua cota. Para ultrapassar o limite de consulta de 20 a 100 QPS, mude para notificações de callback de eventos. Para mais informações, consulte High-concurrency scenarios: use callbacks instead of polling.
  • Tratamento de erros: implemente um mecanismo robusto de retry. Para timeouts de rede ou erros temporários no servidor (5xx), tente novamente usando uma estratégia de backoff exponencial.
  • Redução de ruído: para áudios com muito ruído, faça um pré-processamento com ferramentas como FFmpeg antes de enviá-los para reconhecimento.
  • Seleção de modelo: Utilize Qwen-Audio-ASR para áudios curtos de até 5 minutos. Para áudios mais longos ou processamento assíncrono, utilize Qwen-Audio-ASR-Filetrans.

Modelos e regiões suportados

Singapore

Para chamar os modelos a seguir, utilize uma API Key da região de Singapore:

  • Qwen-Audio-ASR-Filetrans: qwen-audio-3.1-asr-flash-filetrans, qwen-audio-3.0-asr-flash-filetrans
  • Qwen-Audio-ASR: qwen-audio-3.1-asr-flash, qwen-audio-3.0-asr-flash
  • Fun-ASR: fun-asr (versão estável)
  • Fun-ASR-Flash: fun-asr-flash-2026-06-15
  • Qwen3-ASR-Filetrans: qwen3-asr-flash-filetrans (versão estável)
  • Qwen3-ASR-Flash: qwen3-asr-flash (versão estável)

US (Virginia)

Para chamar os modelos a seguir, utilize uma API Key da região dos EUA:

Qwen3-ASR-Flash: qwen3-asr-flash (versão estável)

China (Beijing)

Para chamar os modelos a seguir, utilize uma API Key da região de Beijing:

  • Qwen-Audio-ASR-Filetrans: qwen-audio-3.1-asr-flash-filetrans, qwen-audio-3.0-asr-flash-filetrans
  • Qwen-Audio-ASR: qwen-audio-3.1-asr-flash, qwen-audio-3.0-asr-flash
  • Fun-ASR: fun-asr (versão estável)
  • Fun-ASR-Flash: fun-asr-flash-2026-06-15
  • Qwen3-ASR-Filetrans: qwen3-asr-flash-filetrans (versão estável)
  • Qwen3-ASR-Flash: qwen3-asr-flash (versão estável)
  • Paraformer: paraformer-v2, paraformer-8k-v2

Referência da API

FAQ

P: Como forneço uma URL de áudio publicamente acessível para a API?

Utilize o Alibaba Cloud Object Storage Service (OSS). O OSS oferece armazenamento altamente disponível e confiável, além de permitir a geração de uma URL de acesso público.

Verifique se a URL gerada é acessível pela rede pública: abra a URL em um navegador ou com o comando curl para confirmar que o arquivo de áudio é baixado ou reproduzido (código de status HTTP 200).

P: Como verifico se o formato de áudio atende aos requisitos?

Utilize a ferramenta de código aberto ffprobe para obter rapidamente informações detalhadas sobre o áudio:

# Query the container format (format_name), codec (codec_name), sample rate (sample_rate), and number of channels (channels) of the audio
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 your_audio_file.mp3

P: Como processo o áudio para atender aos requisitos do modelo?

Utilize a ferramenta de código aberto FFmpeg para recortar ou converter o áudio:

  • Recortar áudio: extrair um trecho de um arquivo de áudio longo
# -i: input file
# -ss 00:01:30: set the trim start time (start at 1 minute 30 seconds)
# -t 00:02:00: set the trim duration (trim 2 minutes)
# -c copy: copy the audio stream directly without re-encoding, which is fast
# output_clip.wav: output file
ffmpeg -i long_audio.wav -ss 00:01:30 -t 00:02:00 -c copy output_clip.wav
  • Converter o formato

    Por exemplo, converta qualquer áudio para um arquivo WAV mono, 16 bits e 16 kHz:

# -i: input file
# -ac 1: set the number of channels to 1 (mono)
# -ar 16000: set the sample rate to 16000 Hz (16 kHz)
# -sample_fmt s16: set the sample format to 16-bit signed integer PCM
# output.wav: output file
ffmpeg -i input.mp3 -ac 1 -ar 16000 -sample_fmt s16 output.wav

P: Como melhorar a precisão do reconhecimento?

Os fatores a seguir afetam a precisão do reconhecimento. Verifique cada um e otimize conforme necessário.

Principais fatores:

  1. Qualidade do áudio: a qualidade do dispositivo de gravação, a taxa de amostragem e o ruído ambiental afetam diretamente a clareza do áudio. Uma entrada de áudio de alta qualidade é a base para um reconhecimento preciso.
  2. Características do falante: tom de voz, velocidade de fala, sotaque e diferenças de dialeto (especialmente dialetos raros ou sotaques fortes) aumentam a dificuldade de reconhecimento.
  3. Idioma e vocabulário: mistura de idiomas, termos técnicos ou gírias aumentam a dificuldade de reconhecimento. Configure hotwords para melhorar a precisão de termos específicos do domínio.

Métodos de otimização:

  1. Melhore a qualidade do áudio: use um microfone de alto desempenho, grave na taxa de amostragem recomendada e minimize o ruído ambiental e o eco.
  2. Adapte-se ao falante: para áudios com sotaques fortes ou dialetos notáveis, escolha um modelo que suporte o dialeto correspondente.
  3. Configure hotwords: defina hotwords para termos técnicos, nomes próprios e palavras semelhantes.