实时语音识别（Qwen-ASR-Realtime）Python SDK-API参考

​

前提条件

1. 安装SDK，确保DashScope SDK版本不低于1.25.6。
2. 获取与配置 API Key。
3. 了解WebSocket API。

​

请求参数

• 以下参数通过OmniRealtimeConversation的构造方法设置。
  点击查看示例代码

  Copy

  class MyCallback(OmniRealtimeCallback):
      """实时识别回调处理"""
      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',
          # 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
          url='wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime',
          callback=MyCallback(conversation=None)  # 暂时传None，稍后注入
      )
  # 注入自身到回调
  conversation.callback.conversation = conversation
  

  参数	类型	是否必须	说明
  model	str	是	指定要使用的模型名称。
  callback	OmniRealtimeCallback	是	用于处理服务端事件的回调对象实例。
  url	str	是	语音识别服务地址： 华北2（北京）地域：wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime。调用时请将{WorkspaceId}替换为真实的Workspace ID。 新加坡地域：wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime。调用时请将{WorkspaceId}替换为真实的业务空间ID。

• 以下参数通过OmniRealtimeConversation的update_session方法设置。
  点击查看示例代码

  Copy

  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
  )
  

  参数	类型	是否必须	说明
  output_modalities	List[MultiModality]	是	模型输出模态，固定为[MultiModality.TEXT]。
  enable_turn_detection	bool	否	是否开启服务端语音活动检测（VAD）。关闭后，需手动调用commit()方法触发识别。 默认值：True。 取值范围： True：开启 False：关闭
  turn_detection_type	str	否	服务端VAD类型，固定为 server_vad。
  turn_detection_threshold	float	否	VAD检测阈值。推荐将该值设为0.0。 默认值：0.5。 取值范围：[-1, 1]。 较低的阈值会提高 VAD 的灵敏度，可能将背景噪音误判为语音。较高的阈值则降低灵敏度，有助于在嘈杂环境中减少误触发。
  turn_detection_silence_duration_ms	int	否	VAD断句检测阈值（ms）。静音持续时长超过该阈值将被认为是语句结束。推荐将该值设为400。 默认值：800。 取值范围：[200, 6000]。 较低的值（如 300ms）可使模型更快响应，但可能导致在自然停顿处发生不合理的断句。较高的值（如 1200ms）可更好地处理长句内的停顿，但会增加整体响应延迟。
  transcription_params	TranscriptionParams	否	语音识别相关配置。

• 以下参数通过TranscriptionParams的构造方法设置。
  点击查看示例代码

  Copy

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

  参数	类型	是否必须	说明
  language	str	否	音频源语言。 zh：中文（普通话、四川话、闽南语、吴语） yue：粤语 en：英文 ja：日语 de：德语 ko：韩语 ru：俄语 fr：法语 pt：葡萄牙语 ar：阿拉伯语 it：意大利语 es：西班牙语 hi：印地语 id：印尼语 th：泰语 tr：土耳其语 uk：乌克兰语 vi：越南语 cs：捷克语 da：丹麦语 fil：菲律宾语 fi：芬兰语 is：冰岛语 ms：马来语 no：挪威语 pl：波兰语 sv：瑞典语
  sample_rate	int	否	音频采样率（Hz）。支持16000和8000。 默认值：16000。 设置为 8000 时，服务端会先升采样到16000Hz再进行识别，可能引入微小延迟。建议仅在源音频为8000Hz（如电话线路）时使用。
  input_audio_format	str	否	音频格式。支持pcm和opus。 默认值：pcm。

​

关键接口

​

OmniRealtimeConversation类

def connect(self,) -> None:

def update_session(self,
                       output_modalities: List[MultiModality],
                       voice: str = None,
                       input_audio_format: AudioFormat = AudioFormat.PCM_16000HZ_MONO_16BIT,
                       output_audio_format: AudioFormat = AudioFormat.PCM_24000HZ_MONO_16BIT,
                       enable_input_audio_transcription: bool = True,
                       input_audio_transcription_model: str = None,
                       enable_turn_detection: bool = True,
                       turn_detection_type: str = 'server_vad',
                       prefix_padding_ms: int = 300,
                       turn_detection_threshold: float = 0.2,
                       turn_detection_silence_duration_ms: int = 800,
                       turn_detection_param: dict = None,
                       translation_params: TranslationParams = None,
                       transcription_params: TranscriptionParams = None,
                       **kwargs) -> None:

def append_audio(self, audio_b64: str) -> None:

def commit(self, ) -> None:

def end_session(self, timeout: int = 20) -> None:

def close(self, ) -> None:

def get_session_id(self) -> str:

def get_last_response_id(self) -> str:

​

回调接口（OmniRealtimeCallback）

def on_open(self) -> None:

def on_event(self, message: dict) -> None:

def on_close(self, close_status_code, close_msg) -> None: