Skip to main content

WebSocket access guide

This topic describes the interaction process, API endpoint, and request headers for accessing the Qwen-Audio-TTS realtime speech synthesis service over a WebSocket connection.

API endpoint

The WebSocket API uses the wss:// protocol. The endpoint is as follows:
  • Singapore
  • China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceWhen you call the API, replace {WorkspaceId} with your actual Workspace ID.

Available SDKs

Alibaba Cloud Model Studio has launched workspace-specific domains for the China (Beijing) and Singapore regions, which deliver superior performance and higher stability for inference requests. We recommend that you migrate to the new domains:
  • China (Beijing) region: migrate from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore region: migrate from dashscope-intl.aliyuncs.com to {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Request headers

Add the following information to the request headers:
ParameterTypeRequiredDescription
AuthorizationstringYesAuthentication token in the format Bearer <your_api_key>. Replace <your_api_key> with your actual API Key.
user-agentstringNoClient identifier, which helps the server track the request source.
X-DashScope-WorkSpacestringNoAlibaba Cloud Model Studioworkspace ID。
X-DashScope-DataInspectionstringNoWhether to enable the data compliance check feature. By default, this parameter is not passed or is set to enable. Do not enable this parameter unless necessary.
Authorization authentication is verified during the WebSocket handshake. If the API Key is invalid or missing, the handshake fails and an HTTP 401/403 error is returned.

Interaction process

image
For detailed information about client events and server events, see Client events and Server events. In chronological order, the interaction between the client and the server is as follows:
  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 the task.
  3. Wait for confirmation: The client receives the task-started event returned by the server, indicating that the task has been successfully started and subsequent steps can proceed.
  4. Send the text to be synthesized: The client sends one or more continue-task events containing the text to be synthesized to the server in order. After receiving a complete sentence, the server returns a result-generated event and an audio stream (the text length is constrained; for details, see the description of the text field in the continue-task event).
    You can send the continue-task event multiple times to submit text fragments in order. After receiving the text fragments, the server automatically splits them into sentences:
    • Complete sentences are synthesized immediately, and the client can receive the audio returned by the server
    • Incomplete sentences are cached until complete before being synthesized; when a sentence is incomplete, the server does not return audio
    When a finish-task event is sent, the server forcibly synthesizes all cached content.
  5. Receive audio: Receive the audio stream through the binary channel
  6. Notify the server to finish the task: After all text has been sent, the client sends a finish-task event to notify the server to finish the task, and continues to receive the audio stream returned by the server. This step cannot be skipped; otherwise, the speech data may be incomplete.
  7. Task completion: The client receives the task-finished event returned by the server, indicating that the task has ended.
  8. Close the connection: The client closes the WebSocket connection.
To improve resource utilization, we recommend reusing a WebSocket connection to handle multiple tasks instead of establishing a new connection for each task.
In the same synthesis task, run-task, all continue-task, and finish-task must use the same task_id. Generate a new task_id each time you start a new task (for example, use a UUID). Using different task_ids will result in disordered audio or task failure.

Sample Code

The following examples use a general-purpose WebSocket library to directly send protocol events, using qwen-audio-3.1-tts-flash and the voice longanhuan_v3.1. First, obtain an API Key and configure the DASHSCOPE_API_KEY environment variable, then replace {WorkspaceId} with the workspace ID of the corresponding region; when using another region, replace the endpoint address and API Key as well.
  • Java
  • Python
  • Go
  • C#
  • PHP
  • Node.js
We recommend using the Java DashScope SDK for development. For more information, see Qwen-Audio-TTS Java SDK.The following is a Java WebSocket direct-connection example. Before running it, import the following dependencies:
  • Java-WebSocket
  • jackson-databind
We recommend using Maven or Gradle to manage dependencies. The configuration is as follows:
pom.xml
<dependencies>
    <!-- WebSocket Client -->
    <dependency>
        <groupId>org.java-websocket</groupId>
        <artifactId>Java-WebSocket</artifactId>
        <version>1.5.3</version>
    </dependency>

    <!-- JSON Processing -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.13.0</version>
    </dependency>
</dependencies>
The Java code is as follows:
import com.fasterxml.jackson.databind.ObjectMapper;

import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;

import java.io.FileOutputStream;
import java.io.IOException;
import java.net.URI;
import java.nio.ByteBuffer;
import java.util.*;

public class TTSWebSocketClient extends WebSocketClient {
    private final String taskId = UUID.randomUUID().toString();
    private final String outputFile = "output_" + System.currentTimeMillis() + ".mp3";
    private boolean taskFinished = false;

    public TTSWebSocketClient(URI serverUri, Map<String, String> headers) {
        super(serverUri, headers);
    }

    @Override
    public void onOpen(ServerHandshake serverHandshake) {
        System.out.println("连接成功");

        // 发送run-task事件
        // 如果enable_ssml设为true,只允许发送一次continue-task事件,否则会报错“Text request limit violated, expected 1.”
        String runTaskCommand = "{ \"header\": { \"action\": \"run-task\", \"task_id\": \"" + taskId + "\", \"streaming\": \"duplex\" }, \"payload\": { \"task_group\": \"audio\", \"task\": \"tts\", \"function\": \"SpeechSynthesizer\", \"model\": \"qwen-audio-3.1-tts-flash\", \"parameters\": { \"text_type\": \"PlainText\", \"voice\": \"longanhuan_v3.1\", \"format\": \"mp3\", \"sample_rate\": 22050, \"volume\": 50, \"rate\": 1, \"pitch\": 1, \"enable_ssml\": false }, \"input\": {} }}";
        send(runTaskCommand);
    }

    @Override
    public void onMessage(String message) {
        System.out.println("收到服务端返回的消息:" + message);
        try {
            // Parse JSON message
            Map<String, Object> messageMap = new ObjectMapper().readValue(message, Map.class);

            if (messageMap.containsKey("header")) {
                Map<String, Object> header = (Map<String, Object>) messageMap.get("header");

                if (header.containsKey("event")) {
                    String event = (String) header.get("event");

                    if ("task-started".equals(event)) {
                        System.out.println("收到服务端返回的task-started事件");

                        List<String> texts = Arrays.asList(
                                "床前明月光,疑是地上霜",
                                "举头望明月,低头思故乡"
                        );

                        for (String text : texts) {
                            // 发送continue-task事件
                            sendContinueTask(text);
                        }

                        // 发送finish-task事件
                        sendFinishTask();
                    } else if ("task-finished".equals(event)) {
                        System.out.println("收到服务端返回的task-finished事件");
                        taskFinished = true;
                        closeConnection();
                    } else if ("task-failed".equals(event)) {
                        System.out.println("任务失败:" + message);
                        closeConnection();
                    }
                }
            }
        } catch (Exception e) {
            System.err.println("出现异常:" + e.getMessage());
        }
    }

    @Override
    public void onMessage(ByteBuffer message) {
        System.out.println("收到的二进制音频数据大小为:" + message.remaining());

        try (FileOutputStream fos = new FileOutputStream(outputFile, true)) {
            byte[] buffer = new byte[message.remaining()];
            message.get(buffer);
            fos.write(buffer);
            System.out.println("音频数据已写入本地文件" + outputFile + "中");
        } catch (IOException e) {
            System.err.println("音频数据写入本地文件失败:" + e.getMessage());
        }
    }

    @Override
    public void onClose(int code, String reason, boolean remote) {
        System.out.println("连接关闭:" + reason + " (" + code + ")");
    }

    @Override
    public void onError(Exception ex) {
        System.err.println("报错:" + ex.getMessage());
        ex.printStackTrace();
    }

    private void sendContinueTask(String text) {
        String command = "{ \"header\": { \"action\": \"continue-task\", \"task_id\": \"" + taskId + "\", \"streaming\": \"duplex\" }, \"payload\": { \"input\": { \"text\": \"" + text + "\" } }}";
        send(command);
    }

    private void sendFinishTask() {
        String command = "{ \"header\": { \"action\": \"finish-task\", \"task_id\": \"" + taskId + "\", \"streaming\": \"duplex\" }, \"payload\": { \"input\": {} }}";
        send(command);
    }

    private void closeConnection() {
        if (!isClosed()) {
            close();
        }
    }

    public static void main(String[] args) {
        try {
            // 新加坡和北京地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/model-studio/get-api-key
            // 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:String apiKey = "sk-xxx"
            String apiKey = System.getenv("DASHSCOPE_API_KEY");
            if (apiKey == null || apiKey.isEmpty()) {
                System.err.println("请设置 DASHSCOPE_API_KEY 环境变量");
                return;
            }

            Map<String, String> headers = new HashMap<>();
            headers.put("Authorization", "bearer " + apiKey);
            // 以下为新加坡地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
            TTSWebSocketClient client = new TTSWebSocketClient(new URI("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference"), headers);

            client.connect();

            while (!client.isClosed() && !client.taskFinished) {
                Thread.sleep(1000);
            }
        } catch (Exception e) {
            System.err.println("连接WebSocket服务失败:" + e.getMessage());
            e.printStackTrace();
        }
    }
}