Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Qwen-ASR-Realtime Python SDK - Referência da API

Última atualização: Aug 26, 2026

Transmita áudio para o Qwen-ASR-Realtime via WebSocket e receba resultados de transcrição em tempo real pelo DashScope Python SDK.

Para uma visão geral dos modelos compatíveis, recursos e código de exemplo completo, consulte Reconhecimento de fala em tempo real.

Pré-requisitos

Antes de começar, verifique se você tem:

ImportanteAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

  • China (Beijing): from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from dashscope-intl.aliyuncs.com to {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Replace {WorkspaceId} with your actual Workspace ID. The existing domains remain fully functional.

Parâmetros da solicitação

Construtor OmniRealtimeConversation

Crie uma instância de OmniRealtimeConversation com os seguintes parâmetros.

Clique para visualizar o código de exemplo

from dashscope.audio.qwen_omni import OmniRealtimeConversation, OmniRealtimeCallback

class MyCallback(OmniRealtimeCallback):
    """Callback for real-time recognition"""
    def __init__(self, conversation):
        self.conversation = conversation
        self.handlers = {
            'session.created': self._handle_session_created,
            'conversation.item.input_audio_transcription.completed': self._handle_final_text,
            'conversation.item.input_audio_transcription.text': self._handle_stash_text,
            'input_audio_buffer.speech_started': lambda r: print('======Speech Start======'),
            'input_audio_buffer.speech_stopped': lambda r: print('======Speech Stop======')
        }

    def on_open(self):
        print('Connection opened')

    def on_close(self, code, msg):
        print(f'Connection closed, code: {code}, msg: {msg}')

    def on_event(self, response):
        try:
            handler = self.handlers.get(response['type'])
            if handler:
                handler(response)
        except Exception as e:
            print(f'[Error] {e}')

    def _handle_session_created(self, response):
        print(f"Start session: {response['session']['id']}")

    def _handle_final_text(self, response):
        print(f"Final recognized text: {response['transcript']}")

    def _handle_stash_text(self, response):
        print(f"Got stash result: {response['stash']}")

conversation = OmniRealtimeConversation(
        model='qwen3-asr-flash-realtime',
        # The following URL is for the Chinese mainland. For regions outside
        # the Chinese mainland, use
        # wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime instead.
        url='wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime',
        callback=MyCallback(conversation=None)  # Temporarily pass None and inject it later.
    )
# Inject self into the callback.
conversation.callback.conversation = conversation
ParâmetroTipoObrigatórioDescrição
modelstrSimModelo a ser usado.
callbackOmniRealtimeCallbackSimObjeto de callback que gerencia eventos do servidor.
urlstrSimEndpoint WebSocket.
China (Pequim): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime
Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime. Substitua {WorkspaceId} pelo seu Workspace ID real.

















































Configuração da sessão

Após conectar, chame update_session para configurar os parâmetros da sessão.

Clique para visualizar o código de exemplo

from dashscope.audio.qwen_omni import TranscriptionParams, MultiModality

transcription_params = TranscriptionParams(
    language='zh',
    sample_rate=16000,
    input_audio_format="pcm"
)

conversation.update_session(
    output_modalities=[MultiModality.TEXT],
    enable_turn_detection=True,
    turn_detection_type="server_vad",
    turn_detection_threshold=0.0,
    turn_detection_silence_duration_ms=400,
    enable_input_audio_transcription=True,
    transcription_params=transcription_params
)
ParâmetroTipoObrigatórioDescrição
output_modalitiesList[MultiModality]SimModalidade de saída. Fixo como [MultiModality.TEXT].
enable_turn_detectionboolNãoAtiva a detecção de atividade de voz (VAD) no servidor. Padrão: True. Quando False, chame commit() manualmente para acionar o reconhecimento.
turn_detection_typestrNãoTipo de VAD no servidor. Fixo como server_vad.
turn_detection_thresholdfloatNãoLimiar de sensibilidade do VAD. Padrão: 0.2. Recomendado: 0.0. Intervalo válido: [-1, 1].
Valores menores = maior sensibilidade (pode ser acionado por ruído ambiente). Valores maiores = menos acionamentos falsos em ambientes ruidosos.















turn_detection_silence_duration_msintNãoDuração do silêncio (ms) que marca o fim de uma fala. Padrão: 800. Recomendado: 400. Intervalo válido: [200, 6000].
Valores menores (ex.: 300 ms) = resposta mais rápida, mas pode dividir pausas naturais. Valores maiores (ex.: 1200 ms) = melhor tratamento de pausas em frases longas, porém com maior latência.















transcription_paramsTranscriptionParamsNãoConfigurações de reconhecimento de fala. Consulte TranscriptionParams.

TranscriptionParams

Configure as definições de reconhecimento de fala com o construtor TranscriptionParams.

Clique para visualizar o código de exemplo

transcription_params = TranscriptionParams(
    language='zh',
    sample_rate=16000,
    input_audio_format="pcm"
)
ParâmetroTipoObrigatórioDescrição
languagestrNãoIdioma de origem do áudio. Valores compatíveis:
zh (chinês: mandarim, sichuanês, minnan, wu), yue (cantonês), en (inglês), ja (japonês), ko (coreano), de (alemão), fr (francês), es (espanhol), pt (português), it (italiano), ru (russo), ar (árabe), hi (hindi), id (indonésio), th (tailandês), tr (turco), uk (ucraniano), vi (vietnamita), cs (tcheco), da (dinamarquês), fi (finlandês), fil (filipino), is (islandês), ms (malaio), no (norueguês), pl (polonês), sv (sueco)















sample_rateintNãoTaxa de amostragem de áudio em Hz. Padrão: 16000. Compatível: 16000, 8000. Com 8000, o servidor faz upsampling para 16.000 Hz antes do reconhecimento, o que pode adicionar uma pequena latência. Use 8000 apenas para áudio de origem de 8 kHz, como gravações telefônicas.
input_audio_formatstrNãoFormato de áudio. Padrão: pcm. Compatível: pcm, opus.
corpus_textstrNãoTexto de contexto, vocabulários de entidades ou outras informações de referência para viés contextual. Máximo: 10.000 tokens. Para detalhes, consulte Viés contextual.

Interfaces principais

Classe OmniRealtimeConversation

from dashscope.audio.qwen_omni import OmniRealtimeConversation
MétodoEvento de resposta do servidorDescrição
connect()session.created, session.updatedAbre uma conexão WebSocket com o servidor.
update_session(...)session.updatedConfigura a sessão. Chame após connect(). Se omitido, os padrões são aplicados. Consulte Configuração da sessão para os parâmetros.
append_audio(audio_b64: str)NenhumEnvia um bloco de áudio codificado em Base64 para o buffer de entrada do servidor. Com enable_turn_detection=True, o servidor detecta os limites de fala e faz o commit automaticamente. Com enable_turn_detection=False, o cliente controla o momento do commit (máximo de 15 MiB por evento). Blocos menores melhoram a responsividade do VAD.
commit()input_audio_buffer.committedFaz o commit do áudio armazenado no buffer para reconhecimento. Retorna um erro se o buffer estiver vazio. Desativado quando enable_turn_detection=True.
end_session(timeout: int = 20)session.finishedEncerra a sessão após o servidor concluir o reconhecimento final. No modo VAD (padrão), chame após enviar todo o áudio. No modo manual, chame após commit(). Variante assíncrona: end_session_async().
close()NenhumEncerra a tarefa e fecha a conexão.
get_session_id()NenhumRetorna o ID da sessão atual.
get_last_response_id()NenhumRetorna o ID da resposta mais recente.

Interface OmniRealtimeCallback

Crie uma subclasse de OmniRealtimeCallback e implemente seus métodos para gerenciar eventos do servidor.

from dashscope.audio.qwen_omni import OmniRealtimeCallback
MétodoParâmetrosDescrição
on_open()NenhumChamado quando a conexão WebSocket é estabelecida.
on_event(message: dict)message: um evento do servidorChamado quando um evento do servidor é recebido.
on_close(close_status_code, close_msg)close_status_code: código de status; close_msg: mensagem de logChamado quando a conexão WebSocket é fechada.