time speech synthesis API reference-CosyVoice speech synthesis WebSocket API

Use a WebSocket connection to access the CosyVoice real-time speech synthesis service. This reference covers the interaction workflow, service endpoints, and request headers.

The DashScope SDK currently supports only Java and Python. For other programming languages, use a WebSocket connection to communicate with the service.

User guide: For model details and selection recommendations, see Speech synthesis.

Service endpoints

The service uses a fixed WebSocket URL:

International

If you select the International deployment scope, model inference compute resources are dynamically scheduled worldwide, excluding the Chinese mainland. Static data is stored in your selected region. Supported region: Singapore.

wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference

Mainland China

If you select the Chinese mainland deployment scope, model inference compute resources are restricted to the Chinese mainland. Static data is stored in your selected region. Supported region: China (Beijing).

wss://dashscope.aliyuncs.com/api-ws/v1/inferenceImportant

Always use the wss:// protocol. The URL shown above is fixed. For authorization details, see Request headers.

Request headers

Include the following headers in the request:

Parameter	Type	Required	Description
Authorization	string	Yes	Authentication token in the format Bearer . Replace with your actual API key.
user-agent	string	No	Client identifier for server-side request tracking.
X-DashScope-WorkSpace	string	No	Alibaba Cloud Model Studio workspace ID.
X-DashScope-DataInspection	string	No	Whether to enable data inspection. Defaults to enable when not specified. Unless required, leave this header unset.

Important

Authorization is verified during the WebSocket handshake. If the API key is invalid or missing, the handshake fails with an HTTP 401/403 error.

Interaction workflow

For details about client-side and server-side events, see Client events and Server-side events.

The client and server interact in the following sequence:

1. Establish a connection: The client establishes a WebSocket connection with the server.

2. Start a task: The client sends a run-task event to start a task.

3. Wait for confirmation: The client receives a task-started event from the server, which indicates the task has started and subsequent steps can proceed.

4. Send text for synthesis:

   The client sends one or more continue-task events containing the text to synthesize, in sequence. After receiving a complete sentence, the server returns a result-generated event along with an audio stream. For text length constraints, see the text field in the continue-task event. Note

   You can send multiple continue-task events. Submit text segments in order. The server automatically splits the received text into sentences:

   • Complete sentences are synthesized immediately, and the client receives audio from the server.

   • Incomplete sentences are buffered until complete. The server doesn't return audio for incomplete sentences.

   When you send a finish-task event, the server force-synthesizes all buffered content.

5. Receive audio: Receive the audio stream through the binary channel.

6. Notify the server to end the task:

   After sending all text, the client sends a finish-task event and continues receiving the audio stream. This step is mandatory; skipping it may result in incomplete audio.

7. Receive the task completion event:

   The client receives a task-finished event from the server, which indicates the task is complete.

8. Close the connection: The client closes the WebSocket connection.

Reuse the WebSocket connection across multiple tasks instead of creating a new connection for each task. Important

Within a single synthesis task, the run-task, all continue-task, and finish-task events must use the same task_id. Generate a new task_id (for example, a UUID) for each new task. Using different task_id values causes audio corruption or task failure.