Reconhecimento de fala não em tempo real (Qwen-Audio-ASR) HTTP API - 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 de reconhecimento de fala não em tempo real Qwen-Audio-ASR.

Para requisitos de entrada, como formatos de áudio suportados, limites de tamanho de arquivo e limites de duração, consulte Audio specifications.

Endpoints do service

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Substitua {WorkspaceId} pelo seu Workspace ID real.

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Substitua {WorkspaceId} pelo seu Workspace ID real.

ImportanteO Alibaba Cloud Model Studio lançou domínios específicos para workspaces nas regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos a migração 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

Cabeçalhos da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
`Authorization`	`string`	Sim	O token de autenticação, no formato `Bearer <your_api_key>`. Substitua "`<your_api_key>`" pela sua chave de API real.
`Content-Type`	`string`	Sim	O tipo de mídia do corpo da solicitação. Fixo como `application/json`.
`X-DashScope-SSE`	`string`	Não	Controla se os resultados de streaming são solicitados. Defina como `enable` para solicitar streaming SSE. Defina como `disable` ou omita este parâmetro para retornar apenas o resultado final. ObservaçãoAplica-se apenas a `qwen-audio-3.0-asr-flash`: o streaming SSE está disponível apenas para áudios com pelo menos 1 minuto de duração.

Corpo da solicitação

Os exemplos a seguir usam a configuração para a região Singapore. Substitua "{WorkspaceId}" pelo ID do seu workspace real. A configuração varia entre as regiões, e a chave de API para a região Singapore difere daquela para a região Beijing.

Sem fluxo

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.0-asr-flash",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "{YOUR_AUDIO_URL}"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000"
    }
}'

Com fluxo

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: enable" \
     --data '{
    "model": "qwen-audio-3.0-asr-flash",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "{YOUR_AUDIO_URL}"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000"
    }
}'

Com contexto - sem fluxo

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 @- <<'JSON'
{
    "model": "qwen-audio-3.0-asr-flash",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "Hello"
                    }
                ]
            },
            {
                "role": "assistant",
                "content": [
                    {
                        "type": "text",
                        "text": "Hello, I'm Qwen. How can I help you?"
                    }
                ]
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "{YOUR_AUDIO_URL}"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000"
    }
}
JSON

Com contexto - com fluxo

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: enable" \
     --data @- <<'JSON'
{
    "model": "qwen-audio-3.0-asr-flash",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "Hello"
                    }
                ]
            },
            {
                "role": "assistant",
                "content": [
                    {
                        "type": "text",
                        "text": "Hello, I'm Qwen. How can I help you?"
                    }
                ]
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "{YOUR_AUDIO_URL}"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000"
    }
}
JSON

Base64

É possível passar dados codificados em Base64 (Data URL) no formato data:<mediatype>;base64,<data>.

<mediatype>: O tipo MIME.

O valor depende do formato do áudio. Por exemplo:
- WAV: audio/wav
- MP3: audio/mpeg
<data>: A string do áudio codificada em Base64.

A codificação Base64 aumenta o tamanho dos dados. Para os limites de tamanho e duração dos arquivos de áudio, consulte Especificações de áudio.

Exemplo: data:audio/wav;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjI5LjEwMAAAAAAAAAAAAAAA//PAxABQ/BXRbMPe4IQAhl9

python

import base64, pathlib

# Replace with the path to your own audio file and make sure it meets the audio requirements
file_path = pathlib.Path("{YOUR_AUDIO_FILE}")
base64_str = base64.b64encode(file_path.read_bytes()).decode()
data_uri = f"data:audio/mpeg;base64,{base64_str}"

java

import java.nio.file.*;
          import java.util.Base64;

          public class Main {
              /**
               * Replace with the path to your own audio file and make sure it meets the audio requirements
               */
              public static String toDataUrl(String filePath) throws Exception {
                  byte[] bytes = Files.readAllBytes(Paths.get(filePath));
                  String encoded = Base64.getEncoder().encodeToString(bytes);
                  return "data:audio/mpeg;base64," + encoded;
              }

              public static void main(String[] args) throws Exception {
                  System.out.println(toDataUrl("{YOUR_AUDIO_FILE}"));
              }
          }

import base64, pathlib
import os
import requests

# Replace with the path to your own audio file and make sure it meets the audio requirements
file_path = pathlib.Path("{YOUR_AUDIO_FILE}")
base64_str = base64.b64encode(file_path.read_bytes()).decode()
data_uri = f"data:audio/wav;base64,{base64_str}"

# Replace "{WorkspaceId}" with your actual workspace ID
url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation"

headers = {
    "Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}",
    "Content-Type": "application/json",
    "X-DashScope-SSE": "disable",
}

payload = {
    "model": "qwen-audio-3.0-asr-flash",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": data_uri,
                        },
                    }
                ],
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000",
    },
}

response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.json())

Palavras-chave inline

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.0-asr-flash",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "{YOUR_AUDIO_URL}"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000",
        "vocabulary": {"John Smith": 5, "Jane Doe": 5}
    }
}'

modelstring(Obrigatório)

O nome do modelo.

inputobject(Obrigatório)

As informações de entrada.

Propriedades

messagesarray(object)(Obrigatório)

A lista de mensagens. Contém o áudio a ser reconhecido e, opcionalmente, o contexto de conversação que melhora a precisão do reconhecimento.

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

Uma solicitação pode incluir no máximo 5 mensagens de contexto de cada tipo (input_text e text). Se você exceder esse limite, apenas as 5 mensagens mais recentes serão mantidas. O texto total de contexto por turno (o comprimento combinado dos campos text nas mensagens user e assistant) não pode exceder 400 caracteres, onde cada caractere conta como 1. Qualquer excesso é truncado a partir do final.

ImportanteAo incluir contexto, a ordem das mensagens em messages é importante: as mensagens de contexto devem ser organizadas por turno de conversação. Dentro de cada turno, a mensagem user (do tipo input_text) deve vir antes da mensagem assistant correspondente (do tipo text). A mensagem user que contém input_audio deve ser o último item no array messages.

Propriedades

rolestring(Obrigatório)

A função da mensagem. Valores válidos:

user (Obrigatório): Uma mensagem do usuário. Quando o tipo é input_audio, contém o áudio a ser reconhecido. Quando o tipo é input_text, contém resultados de reconhecimento de turnos anteriores ou uma lista de palavras específicas de domínio (opcional, usada como contexto).
assistant (Opcional, contexto): Respostas do modelo de linguagem grande em turnos anteriores.

contentarray(object)(Obrigatório)

A lista de conteúdo da mensagem.

Propriedades

typestring(Obrigatório)

O tipo de conteúdo. Cada solicitação precisa de pelo menos uma mensagem do tipo input_audio. Valores válidos:

input_audio (Obrigatório): A entrada de áudio a ser reconhecida (a função é user). Você também deve passar o objeto input_audio.
input_text (Opcional, contexto): Resultados de reconhecimento da fala do usuário de turnos anteriores ou uma lista de palavras específicas de domínio (a função é user). Você também deve passar o campo text.
text (Opcional, contexto): Respostas do modelo de linguagem grande em turnos anteriores (a função é assistant). Você também deve passar o campo text.

input_audioobject(Condicionalmente obrigatório)

Obrigatório quando type é input_audio.

Propriedades

datastring(Obrigatório)

Os dados de áudio a serem reconhecidos. Para requisitos de entrada, como formatos de áudio suportados, limites de tamanho de arquivo e limites de duração, consulte Audio specifications. Dois métodos são suportados:

URL do arquivo de áudio: Passe uma URL publicamente acessível para o arquivo de áudio.
Data URI em Base64: Passe os dados de áudio codificados em Base64 como um Data URI. O valor é o prefixo data:{MIME_TYPE};base64, concatenado com os dados de áudio codificados em Base64. Os tipos MIME suportados incluem audio/wav e audio/mp3.

Exemplo (URL): https://example.com/audio/sample.wav

Exemplo (Base64): data:audio/wav;base64,{BASE64_ENCODED_DATA}

textstring(Condicionalmente obrigatório)

Quando type é 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 é text, insira as respostas do modelo de linguagem grande de turnos anteriores. O comprimento do texto é medido em caracteres, onde cada caractere conta como 1. O comprimento combinado dos campos text em todas as mensagens em um único turno de contexto não pode exceder 400 caracteres. Qualquer excesso é truncado a partir do final.

parametersobject(Obrigatório)

Os parâmetros do modelo.

ObservaçãoO refinamento de texto está desativado por padrão e ainda não está disponível para qwen-audio-3.0-asr-flash. qwen-audio-3.1-asr-flash oferece refinamento de texto nativo.

Refinamento de texto: Ao transcrever a fala, o modelo remove palavras de preenchimento sem significado e repetições por gagueira, trata autocorreções, aprimora expressões coloquiais e padroniza a pontuação e a formatação. O resultado é mais conciso, fluente e legível, preservando ao máximo a intenção final e as informações importantes do falante.

Propriedades

speaker_diarization_enabled boolean (Opcional)

ObservaçãoAplica-se apenas a qwen-audio-3.1-asr-flash.

Especifica se a diarização de falantes está ativada. Padrão: false. Quando definido como true, a resposta usa speaker_id para distinguir falantes e inclui output.sentences. Quando ativada, keep_dialect e language_hints são ignorados.

keep_dialect boolean (Opcional)

ObservaçãoAplica-se apenas a qwen-audio-3.1-asr-flash.

Especifica se as expressões dialetais são preservadas. Padrão: false. Defina false para transcrever o dialeto em texto em mandarim padrão, ou true para preservar expressões dialetais.

formatstring(Obrigatório)

O formato do áudio. Defina este valor para corresponder ao seu formato de áudio real. Os valores suportados incluem wav, mp3 e opus. Para mais detalhes, consulte Audio specifications.

sample_ratestring(Opcional)

A taxa de amostragem do áudio, em Hz. Por exemplo, 16000 significa uma taxa de amostragem de 16 kHz. Para mais detalhes, consulte Audio specifications.

vocabulary_idstring(Opcional)

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.

vocabularyobject(Opcional)

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 da sessão.

Quando configuradas juntamente com palavras-chave pré-compiladas, apenas as palavras-chave instantâneas têm efeito. Para detalhes de uso, consulte Instant hotwords.

ImportanteApenas qwen-audio-3.0-asr-flash suporta palavras-chave inline.

language_hints array[string](Opcional)

Os códigos de idioma a reconhecer. Se o idioma não for conhecido, omita este parâmetro para que o modelo o detecte automaticamente. Você pode definir até 4 valores. Se definir mais, apenas os 4 primeiros terão efeito.

Especificar os códigos de idioma pode melhorar a precisão do reconhecimento.

Códigos de idioma compatíveis

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

O qwen-audio-3.1-asr-flash também oferece suporte aos seguintes códigos de idioma:

tr: turco
fa: persa
mr: marati
ml: malaiala
ne: nepalês
ky: quirguiz
az: azerbaijano
ka: georgiano
hy: armênio
sl: esloveno
sq: albanês
et: estoniano
lv: letão
lt: lituano
ca: catalão
eu: basco
gl: galego
or: oriá
dv: divehi
as: assamês
ku: curdo
tig: tigré
fy: frísio ocidental
ba: bashkir
be: bielorrusso
tt: tártaro
ia: interlíngua
mhr: mari oriental
tok: toki pona

Corpo da resposta

Sem fluxo

{
    "output": {
        "sentence": {
            "begin_time": 760,
            "channel_id": 0,
            "end_time": 3800,
            "sentence_end": true,
            "sentence_id": 1,
            "text": "Hello World, this is Alibaba Speech Lab.",
            "words": [
                {"begin_time": 760, "end_time": 1040, "fixed": true, "punctuation": "", "text": "Hello"},
                {"begin_time": 1040, "end_time": 1240, "fixed": true, "punctuation": ",", "text": " World"},
                {"begin_time": 1360, "end_time": 1880, "fixed": true, "punctuation": "", "text": "this is"},
                {"begin_time": 1880, "end_time": 2520, "fixed": true, "punctuation": "", "text": "Alibaba"},
                {"begin_time": 2520, "end_time": 2840, "fixed": true, "punctuation": "", "text": "Speech"},
                {"begin_time": 2840, "end_time": 3800, "fixed": true, "punctuation": ".", "text": "Lab"}
            ]
        },
        "text": "Hello World, this is Alibaba Speech Lab."
    },
    "usage": {
        "duration": 4
    },
    "request_id": "40e0734d-096f-9ae3-86c1-a8c013287561"
}

Com fluxo

A resposta de streaming SSE usa o seguinte formato de evento:

id:{sequence_number}
          event:result
          :HTTP_STATUS/200
          data:{JSON_data}

Exemplo de resposta:

id:1
event:result
:HTTP_STATUS/200
data:{"output":{"sentence":{"sentence_id":1,"sentence_end":true,"end_time":3800,"words":[{"end_time":1040,"punctuation":"","begin_time":760,"fixed":true,"text":"Hello"},{"end_time":1240,"punctuation":",","begin_time":1040,"fixed":true,"text":" World"},{"end_time":1880,"punctuation":"","begin_time":1360,"fixed":true,"text":"this is"},{"end_time":2520,"punctuation":"","begin_time":1880,"fixed":true,"text":"Alibaba"},{"end_time":2840,"punctuation":"","begin_time":2520,"fixed":true,"text":"Speech"},{"end_time":3800,"punctuation":".","begin_time":2840,"fixed":true,"text":"Lab"}],"begin_time":760,"text":"Hello World, this is Alibaba Speech Lab.","channel_id":0},"text":"Hello World, this is Alibaba Speech Lab."},"usage":{"duration":4},"request_id":"fc1582e4-935c-9fc2-a482-a98bf43daa69"}

request_idstring

O identificador exclusivo desta solicitação.

outputobject

O resultado de saída.

Propriedades

textstring

O texto completo reconhecido acumulado até o momento.

sentences array[object]

ObservaçãoAplica-se apenas a qwen-audio-3.1-asr-flash.

Retornado quando a diarização de falantes está ativada. Contém resultados da frase atual e das anteriores. Cada elemento tem a mesma estrutura de sentence.

sentenceobject

Os detalhes da frase atual.

Propriedades

speaker_id integer | null

ObservaçãoAplica-se apenas a qwen-audio-3.1-asr-flash.

O ID usado para distinguir falantes. Contém um ID quando a diarização está ativada, ou null caso contrário.

sentence_idinteger

O número da frase, começando em 1.

sentence_endboolean

Indica se este é o resultado final para a frase. true indica que o reconhecimento da frase foi concluído.

begin_timeinteger

O horário de início da frase, em milissegundos.

end_timeinteger

O horário de término da frase, em milissegundos. Retornado apenas quando sentence_end é true.

textstring

O texto reconhecido da frase atual.

channel_idinteger

O número do canal, começando em 0.

wordsarray

A lista de carimbos de data/hora no nível de palavra.

Propriedades

speaker_id integer | null

ObservaçãoAplica-se apenas a qwen-audio-3.1-asr-flash.

O ID do falante desta palavra. Contém um ID quando a diarização está ativada, ou null caso contrário.

textstring

O texto da palavra.

begin_timeinteger

O horário de início da palavra, em milissegundos.

end_timeinteger

O horário de término da palavra, em milissegundos.

punctuationstring

O sinal de pontuação após a palavra. Uma string vazia quando não há pontuação.

fixedboolean

Indica se a palavra está estabilizada. false indica que o carimbo de data/hora da palavra pode ser ajustado em eventos subsequentes.

usageobject

As informações de uso. Retornadas apenas quando sentence_end é true.

Propriedades

durationinteger

A duração do áudio processado, em segundos.

input_tokens integer

ObservaçãoAplica-se apenas a qwen-audio-3.1-asr-flash.

O número de tokens de entrada consumidos por esta solicitação.

output_tokens integer

ObservaçãoAplica-se apenas a qwen-audio-3.1-asr-flash.

O número de tokens de saída consumidos por esta solicitação.

total_tokens integer

ObservaçãoAplica-se apenas a qwen-audio-3.1-asr-flash.

O total de tokens consumidos por esta solicitação, igual à soma de input_tokens e output_tokens.

Lógica de processamento de resultados de fluxo SSE

No modo de fluxo, o cliente precisa lidar com o seguinte:

Para cada evento SSE recebido, analise o JSON no campo data.
Para qwen-audio-3.0-asr-flash, use output.sentence.sentence_end para determinar se a frase atual terminou. Se for true, o reconhecimento foi concluído e os timestamps de palavras estão estabilizados, podendo ser usados como resultado final. Se for false, o reconhecimento continua, e o texto e os timestamps podem ser atualizados em eventos posteriores.
As informações de usage são retornadas apenas nos eventos de fim de frase e incluem a duração do áudio processado. Para qwen-audio-3.1-asr-flash, também incluem os tokens de entrada, de saída e totais da solicitação. Esse modelo é cobrado pelo uso de tokens.

Para qwen-audio-3.1-asr-flash sem diarização de falantes, o timestamp de uma palavra só se torna definitivo quando output.sentence.words[i].fixed é true. Antes disso, pode mudar. Quando a diarização está ativada, leia os resultados da frase atual e das anteriores em output.sentences.