Skip to main content

Qwen-Omni-Realtime WebSocket access

Qwen-Omni-Realtime WebSocket access

Scope of Application

This document is intended for Qwen-Omni-Realtime. The example model is qwen3.8-omni-flash-realtime; configurations for qwen3.5-omni-plus-realtime and qwen3.5-omni-flash-realtime can be found in the event reference. Parameters for legacy models qwen3-omni-flash-realtime-2025-09-15 are detailed in Python SDK.
  • Use the API Key and Workspace ID corresponding to your selected region and workspace.
  • Beijing domain: {WorkspaceId}.cn-beijing.maas.aliyuncs.com; Singapore domain: {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com.
  • Long-term API keys are stored on the server and should not be placed in browsers or mobile applications.

Addresses and Authentication

Beijing: wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtime Singapore: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtime qwen3.8-omni-flash-realtime must use the workspace-specific domain name. Older models may continue to use their original domains: Beijing uses wss://dashscope.aliyuncs.com, and Singapore uses wss://dashscope-intl.aliyuncs.com. For details, see Python SDK. Set Authorization: Bearer <API_KEY> in the WebSocket handshake request header. Replace the workspace ID and the actual model name; do not place long-term API keys in browsers or mobile apps. An optional user-agent request header is used to identify the client. General WebSocket integration documentation also lists X-DashScope-WorkSpace (workspace ID) and X-DashScope-DataInspection (data compliance check configuration), which are used as required by the model. For instructions on generating temporary API keys and their permissions, see Generate Temporary API Key.

Session Configuration

Send session.update after establishing the connection and receiving session.created. Send input only after receiving session.updated confirmation; handle errors via error events. The following examples correspond to qwen3.8-omni-flash-realtime; other versions should use the configurations from their respective event references, without mixing field levels. 
{
  "type": "session.update",
  "session": {
    "modalities": [
      "text",
      "audio"
    ],
    "voice": "Tina",
    "turn_detection": {
      "type": "server_vad"
    }
  }
}

Input, Results, and Termination

Audio is sent via input_audio_buffer.append; input formats, submission conditions, and image input limits are described in Client Events. Process the results, status, and errors in Server Events; do not consider connection establishment as completion of the business request. The timing for automatic rounds, Manual mode, Function Calling, and MCP is outlined in Interaction Flow. After receiving the required results, close the WebSocket connection.

Error Handling

When a handshake fails, verify the domain name, region, workspace, API Key, model name, and model activation status and permissions. After the connection is established, locate the issue based on the error event, and refer to Error Codes. Retain the event ID for troubleshooting; do not assume protocol support is lacking simply because there is no response.

SDKs and reference