Skip to main content
WebSocket

WebSocket connection overview

Learn about WebSocket endpoints, authentication, Realtime and Inference interaction flows, and model-specific events.

Prerequisites

  • Activate the target model or application and confirm its supported regions.
  • Obtain an API key for the region and workspace you will use. See Token authentication.
  • Obtain your Workspace ID if you use a workspace-specific domain.
For protocol selection and supported models, see Realtime API overview.

Request headers

Set Authorization in the WebSocket handshake request. Use other headers as described in the target model's parameter reference.
HeaderRequiredDescription
AuthorizationYesPass the API key as Bearer <API_KEY>.
user-agentNoIdentifies the client.
X-DashScope-WorkSpaceModel-specificSpecifies a workspace ID. See the model-specific header reference for usage.
X-DashScope-DataInspectionModel-specificConfigures data inspection. See the model-specific header reference for supported values and applicability.

Endpoints

Use wss:// and select the API path and model-name location for your target model. The table below lists connection methods by model. For supported models and regions, see the corresponding model documentation.
Model familyAPI pathModel-name location
Qwen-Omni-Realtime/api-ws/v1/realtimeURL query parameter model
Qwen-Audio-TTS/CosyVoice/api-ws/v1/inferencepayload.model in run-task
Qwen-TTS-Realtime/api-ws/v1/realtimeURL query parameter model
Qwen-Audio-ASR/Fun-ASR/Paraformer/api-ws/v1/inferencepayload.model in run-task
Qwen-ASR-Realtime/api-ws/v1/realtimeURL query parameter model
Qwen-Audio-Realtime/api-ws/v1/realtimeURL query parameter model
Qwen-LiveTranslate-Realtime/api-ws/v1/realtimeURL query parameter model
Workspace-specific domains:
RegionWorkspace-specific domain
China (Beijing){WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Replace {WorkspaceId} with your workspace ID. Examples: 
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtime
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference
Qwen-TTS-Realtime also supports the public domains dashscope.aliyuncs.com for Beijing and dashscope-intl.aliyuncs.com for Singapore, with the same /api-ws/v1/realtime path. The API key must match the region.

Common interaction flows

/api-ws/v1/realtime uses a session-based protocol, while /api-ws/v1/inference uses a task-based protocol.

Realtime protocol

After connecting, the client configures the session with session.update and waits for session.updated before sending input. The target model determines how to commit input, trigger a response, and finish the session.
Realtime session configuration, input, output, and termination flow
  1. Connect: Specify the model in the URL's model query parameter and include the API key in the request headers. After a successful handshake, the server sends session.created.
  2. Configure the session: Send session.update to configure supported audio formats, output modalities, voices, or speech detection parameters, then wait for session.updated. See the model-specific client event reference for supported session parameters.
  3. Send input: Send Base64-encoded audio with input_audio_buffer.append. For Qwen-TTS, send text with input_text_buffer.append. Models that support image input use input_image_buffer.append; follow the model's image and audio timing requirements.
  4. Commit and receive results: In automatic modes, the server triggers processing. In manual modes, send input_audio_buffer.commit or input_text_buffer.commit according to the input type. Whether response.create is also required, and which result events to handle, depends on the model. See the comparison below.
  5. Finish the session: For models that support a finish event, send session.finish and wait for session.finished and remaining results. For other models, close the WebSocket after receiving the results. response.done marks the end of one response, not the connection. For ASR-only models, transcription-completion events mark the end of recognition.

Inference protocol

The client sends run-task and waits for task-started before transmitting input. Speech recognition uses binary audio frames; speech synthesis sends text with continue-task. When input ends, send finish-task and wait for task-finished.
Inference task flows for speech recognition and speech synthesis
  1. Connect: Use /api-ws/v1/inference and include the API key in the request headers.
  2. Start a task: Send run-task, specifying the model in payload.model and parameters such as the input format. Generate a unique header.task_id and wait for task-started.
  3. Send input and receive results:
    • Speech recognition: Send binary audio frames and receive recognition results through result-generated.
    • Speech synthesis: Send text in payload.input.text of continue-task and receive binary audio frames. The model may also return information such as timestamps through result-generated.
  4. Finish the task: After sending finish-task, keep receiving remaining results until task-finished arrives. All run-task, continue-task, and finish-task events for the same task must use the same header.task_id. Then close the connection, or reuse it as supported by the model.

Model differences

Realtime models

The table below summarizes input triggers and session termination. For all supported VAD types, audio formats, and other parameter values, see the model-specific event references.
ModelInput and response triggerTermination
Qwen3.8-Omni / Qwen3.5-OmniVAD modes trigger responses automatically. In Manual mode, send input_audio_buffer.commit followed by response.create.Close the connection after receiving the results.
Qwen-TTS-Realtimeserver_commit commits text automatically. In commit mode, send input_text_buffer.commit; response.create is not required.session.finish → session.finished
Qwen-ASR-RealtimeVAD mode processes input automatically. In Manual mode, send input_audio_buffer.commit; response.create is not required.session.finish → session.finished
Qwen-Audio-RealtimeAutomatic modes detect turns on the server. In Manual mode, send input_audio_buffer.commit followed by response.create.Close the connection after receiving the results.
Qwen3.8-LiveTranslateConfigure output modalities with output_modalities and turn detection with audio.input.turn_detection. Stream audio and send session.finish when input ends.session.finish → session.finished
Qwen3.5-LiveTranslateConfigure the session with modalities and turn_detection. In Manual mode, input_audio_buffer.commit triggers a response without response.create.session.finish → session.finished
The main output events are listed below. The events returned depend on the configured output modalities.
ModelMain output events
Qwen-Omni-Realtimeresponse.text.delta / response.audio_transcript.delta / response.audio.delta / response.done
Qwen-TTS-Realtimeresponse.audio.delta / response.done
Qwen-ASR-Realtimeconversation.item.input_audio_transcription.text / conversation.item.input_audio_transcription.completed
Qwen-Audio-Realtimeresponse.audio_transcript.delta / response.audio.delta / response.done
Qwen3.8-LiveTranslateresponse.text.delta / response.audio_transcript.delta / response.audio.delta / response.done
Qwen3.5-LiveTranslateresponse.text.text / response.audio_transcript.text / response.audio.delta / response.done
Translation event names depend on the model version: Qwen3.8-LiveTranslate uses .delta, while Qwen3.5-LiveTranslate uses .text. For example, translated audio transcripts use response.audio_transcript.delta and response.audio_transcript.text, respectively.

Inference models

Qwen-Audio-TTS/CosyVoice uses the run-task → task-started → continue-task → finish-task → task-finished task flow. Qwen-Audio-ASR/Fun-ASR/Paraformer speech recognition sends binary audio frames after task-started. Both types report task errors through task-failed.

Model-specific integration guides

Real-time omni

Real-time speech synthesis

Qwen-Audio-TTS/CosyVoice

Qwen-TTS-Realtime

Sambert

Real-time speech recognition

Qwen-Audio-3.x-ASR-Flash-Streaming/Qwen-Audio-3.1-ASR-Flash-Message/Fun-ASR-Realtime

Qwen-ASR-Realtime

Paraformer

Real-time voice conversation

Qwen-Audio-Realtime

Real-time audio and video translation

Qwen-Livetranslate-Realtime

Error handling

  • Handshake failure: Use the HTTP status and error message to check the endpoint, API key, workspace, and model permissions. For 401/403, check authentication first.
  • Model unavailable or not activated: Verify the model name, service activation, and region.
  • Realtime errors: Handle error events and read their type and message. Adjust the event type or parameters in the request based on the error message.
  • Inference errors: A task-failed event indicates that the task has failed. Read header.error_code and header.error_message for the cause.
After correcting the configuration or handling a network interruption, reconnect and configure a new session or start a new task as required by the protocol. See Error codes.
API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
World models
Audio
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More