跳转到主要内容

WebSocket 接入指南

本文介绍通过WebSocket连接访问CosyVoice实时语音合成服务的交互流程、接口地址和请求头。

接口地址

WebSocket 接口使用 wss:// 协议,地址如下: wss://maas.qianwenaiapi.com/api-ws/v1/inference

请求头

请求头中需添加如下信息:
参数类型是否必选说明
Authorizationstring是鉴权令牌,格式为 Bearer $DASHSCOPE_API_KEY,将 $DASHSCOPE_API_KEY 替换为实际的 API Key。
user-agentstring否客户端标识,便于服务端追踪来源。
X-DashScope-WorkSpacestring否千问AI平台业务空间ID。
X-DashScope-DataInspectionstring否是否启用数据合规检测功能。默认不传或设为enable。如非必要,请勿启用该参数。
Authorization 鉴权在 WebSocket 握手阶段验证。如果 API Key 无效或缺失,握手将失败并返回 HTTP 401/403 错误。

交互流程

image
客户端事件和服务端事件的详细说明,请参见客户端事件和服务端事件。 按时间顺序,客户端与服务端的交互流程如下:
  1. 建立连接:客户端与服务端建立WebSocket连接。
  2. 开启任务:客户端发送run-task事件以开启任务。
  3. 等待确认:客户端收到服务端返回的task-started事件,标志着任务已成功开启,可以进行后续步骤。
  4. 发送待合成文本: 客户端按顺序向服务端发送一个或多个包含待合成文本的continue-task事件,服务端接收到完整语句后返回result-generated事件和音频流(文本长度有约束, 详情参见continue-task事件中text字段描述)。
    支持多次发送continue-task事件,按顺序提交文本片段。服务端接收文本片段后自动进行分句:
    • 完整语句立即合成,此时客户端能够接收到服务端返回的音频
    • 不完整语句缓存至完整后合成,语句不完整时服务端不返回音频
    当发送finish-task事件时,服务端会强制合成所有缓存内容。
  5. 接收音频:通过 binary 通道接收音频流
  6. 通知服务端结束任务: 待文本发送完毕后,客户端发送finish-task事件通知服务端结束任务,并继续接收服务端返回的音频流。此步骤不可省略,否则可能导致语音数据不完整。
  7. 任务结束: 客户端收到服务端返回的task-finished事件,标志着任务结束。
  8. 关闭连接:客户端关闭WebSocket连接。
为提高资源利用率,建议复用 WebSocket 连接处理多个任务,而非为每个任务建立新连接。
同一次合成任务中,run-task、所有 continue-task、finish-task 必须使用相同的 task_id。每次发起新任务时生成新的 task_id(如使用 UUID)。使用不同 task_id 会导致音频错乱或任务失败。

示例代码

以下示例使用通用 WebSocket 库直接发送协议事件,使用 cosyvoice-v3-flash 和音色 longanyang。先获取 API Key并配置 DASHSCOPE_API_KEY 环境变量。
  • Java
  • Python
  • Go
  • C#
  • PHP
  • Node.js
建议使用 Java DashScope SDK 进行开发,请参见CosyVoice Java SDK。以下是 Java WebSocket 直连示例,运行前请导入以下依赖:
  • Java-WebSocket
  • jackson-databind
推荐使用Maven或Gradle管理依赖包,其配置如下:
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>
Java代码如下:
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\": \"cosyvoice-v3-flash\", \"parameters\": { \"text_type\": \"PlainText\", \"voice\": \"longanyang\", \"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 {
            // 若没有配置环境变量,请用千问AI平台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);
            TTSWebSocketClient client = new TTSWebSocketClient(new URI("wss://maas.qianwenaiapi.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();
        }
    }
}