跳转到主要内容

WebSocket 接入指南

Qwen-ASR-Realtime 实时语音识别服务通过 WebSocket 协议,接收实时音频流并实时转写。支持 VAD 模式 和 Manual 模式 交互流程。

**用户指南:**关于模型介绍和选型建议请参见语音识别,示例代码请参见实时语音识别。

接口地址

WebSocket URL 固定如下,通过查询参数 model 指定要调用的模型名称(将 <model_name> 替换为实际的模型): wss://maas.qianwenaiapi.com/api-ws/v1/realtime?model=<model_name>
URL 必须使用 wss:// 协议。Authorization 在请求头中设置(参见请求头),模型通过 URL 查询参数 model 指定。

请求头

请求头中需添加如下信息:
参数类型是否必选说明
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 错误。

交互流程

客户端事件和服务端事件的详细说明,请参见客户端事件和服务端事件。 支持两种交互模式:
  • VAD 模式(默认):服务端自动检测语音的起点和终点(断句),适用于实时对话、会议记录等场景。
  • Manual 模式:由客户端控制断句,适用于客户端能明确判断语句边界的场景,如聊天软件中的发送语音。
该模型不返回转写文本的句级、字词级时间戳。VAD 事件中的语音起止时间用于描述语音活动边界,字段说明见对应事件。

VAD 模式(默认)

silence_duration_ms 的服务端默认值为 800,对话、聊天等需要快速断句的场景可参考 400;threshold 的服务端默认值为 0.2。完整配置见客户端事件。 服务端自动检测语音的起点和终点(断句)。开发者只需持续发送音频流,服务端会在检测到一句话结束时自动返回最终识别结果。此模式适用于实时对话、会议记录等场景。 **启用方式:**配置客户端session.update事件的session.turn_detection参数。
image
  • 客户端通过发送input_audio_buffer.append事件将音频追加到缓冲区。
  • 服务端在检测到语音时返回input_audio_buffer.speech_started事件。 注意:如果客户端尚未收到该事件,就直接发送session.finish结束会话,服务端会直接返回session.finished事件,随后客户端需主动断开连接。
  • 客户端继续发送input_audio_buffer.append事件提交音频。
  • 客户端在音频提交完后,发送session.finish事件通知服务端结束当前会话。
    在 VAD 模式下,推完音频后必须先发送session.finish事件再关闭连接。如果客户端直接关闭 WebSocket 连接而未发送该事件,服务端将丢弃当前 in_progress item,conversation.item.input_audio_transcription.completed 等事件将不会到达。建议在调用 ws.Close() 之前,先发送 {"type":"session.finish"},并等待收到session.finished事件后再关闭连接。
  • 服务端在检测到语音结束时返回input_audio_buffer.speech_stopped事件。
  • 服务端返回input_audio_buffer.committed事件。
  • 服务端返回conversation.item.created事件。
  • 服务端返回conversation.item.input_audio_transcription.text事件,其中包含语音识别实时结果。
  • 服务端返回conversation.item.input_audio_transcription.completed事件,其中包含语音识别最终结果。
  • 服务端返回session.finished事件,通知客户端识别结束,此时客户端需要主动断开连接。

Manual 模式

由客户端控制断句。客户端需要发送完一整句话的音频后,再发送一个input_audio_buffer.commit事件来通知服务端。此模式适用于客户端能明确判断语句边界的场景,如聊天软件中的发送语音。 **启用方式:**将客户端session.update事件的session.turn_detection设为null。
image
  • 客户端通过发送input_audio_buffer.append事件将音频追加到缓冲区。
  • 客户端通过发送input_audio_buffer.commit事件来提交输入音频缓冲区。 该提交会在对话中创建一个新的用户消息项。
  • 客户端发送session.finish事件通知服务端结束当前会话。
  • 服务端返回input_audio_buffer.committed事件进行响应。
  • 服务端返回conversation.item.input_audio_transcription.text事件,其中包含语音识别实时结果。
  • 服务端返回conversation.item.input_audio_transcription.completed事件,其中包含语音识别最终结果。
  • 服务端返回session.finished事件,通知客户端识别结束,此时客户端需要主动断开连接。

调用示例

以下示例使用 qwen3-asr-flash-realtime。在控制台获取 API Key 和 Base URL,分别配置环境变量 DASHSCOPE_API_KEY 和 DASHSCOPE_BASE_URL。 下载示例音频并保存为 asr_example.wav。音频为 16 kHz、单声道、16-bit PCM 编码的 WAV 文件。
示例代码读取 asr_example.pcm(PCM16、16 kHz、单声道)。如仅有 MP3/WAV 等格式,可使用 ffmpeg 转换:
ffmpeg -i asr_example.wav -ar 16000 -ac 1 -f s16le asr_example.pcm
使用非 VAD(Manual)模式时,建议单次会话持续发送的音频时长累加不超过 60 秒。
  • Java
  • Python
  • Go
  • Node.js
  • C#
  • PHP
在运行示例前,请确保已安装Java-WebSocket依赖:
Maven
<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.5.6</version>
</dependency>
<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20240303</version>
</dependency>
import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;
import org.json.JSONObject;

import java.net.URI;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.logging.*;

public class QwenASRRealtimeClient {

    private static final Logger logger = Logger.getLogger(QwenASRRealtimeClient.class.getName());
    private static final String API_KEY = System.getenv("DASHSCOPE_API_KEY");
    private static final String MODEL = "qwen3-asr-flash-realtime";

    // 控制是否使用 VAD 模式
    private static final boolean enableServerVad = true;

    private static final AtomicBoolean isRunning = new AtomicBoolean(true);
    private static WebSocketClient client;

    public static void main(String[] args) throws Exception {
        initLogger();

        String baseUrl = "wss://" + URI.create(System.getenv("DASHSCOPE_BASE_URL")).getHost() + "/api-ws/v1/realtime";
        String url = baseUrl + "?model=" + MODEL;
        logger.info("Connecting to server: " + url);

        client = new WebSocketClient(new URI(url)) {
            @Override
            public void onOpen(ServerHandshake handshake) {
                logger.info("Connected to server.");
                sendSessionUpdate();
            }

            @Override
            public void onMessage(String message) {
                try {
                    JSONObject data = new JSONObject(message);
                    String eventType = data.optString("type");

                    logger.info("Received event: " + data.toString(2));

                    // 最终识别结果在 transcription.completed 事件中
                    if ("conversation.item.input_audio_transcription.completed".equals(eventType)) {
                        logger.info("Final transcript: " + data.optString("transcript"));
                    }

                    // 收到结束事件 → 停止发送线程并关闭连接
                    if ("session.finished".equals(eventType)) {
                        logger.info("Closing WebSocket connection after session finished...");

                        isRunning.set(false); // 停止发送音频线程
                        if (this.isOpen()) {
                            this.close(1000, "ASR finished");
                        }
                    }
                } catch (Exception e) {
                    logger.severe("Failed to parse message: " + message);
                }
            }

            @Override
            public void onClose(int code, String reason, boolean remote) {
                logger.info("Connection closed: " + code + " - " + reason);
            }

            @Override
            public void onError(Exception ex) {
                logger.severe("Error: " + ex.getMessage());
            }
        };

        // 添加请求头
        client.addHeader("Authorization", "Bearer " + API_KEY);
        client.addHeader("OpenAI-Beta", "realtime=v1");

        client.connectBlocking(); // 阻塞直到连接建立

        // 替换为待识别的音频文件路径
        String localAudioPath = "asr_example.pcm";
        Thread audioThread = new Thread(() -> {
            try {
                sendAudio(localAudioPath);
            } catch (Exception e) {
                logger.severe("Audio sending thread error: " + e.getMessage());
            }
        });
        audioThread.start();
    }

    /** 会话更新事件(开启/关闭 VAD) */
    private static void sendSessionUpdate() {
        JSONObject eventNoVad = new JSONObject()
                .put("event_id", "event_123")
                .put("type", "session.update")
                .put("session", new JSONObject()
                        .put("modalities", new String[]{"text"})
                        .put("input_audio_format", "pcm")
                        .put("sample_rate", 16000)
                        // .put("input_audio_transcription", new JSONObject()
                        //         .put("language", "zh"))
                        .put("turn_detection", JSONObject.NULL) // 手动模式
                );

        JSONObject eventVad = new JSONObject()
                .put("event_id", "event_123")
                .put("type", "session.update")
                .put("session", new JSONObject()
                        .put("modalities", new String[]{"text"})
                        .put("input_audio_format", "pcm")
                        .put("sample_rate", 16000)
                        // .put("input_audio_transcription", new JSONObject()
                        //         .put("language", "zh"))
                        .put("turn_detection", new JSONObject()
                                .put("type", "server_vad")
                                .put("threshold", 0.2)
                                .put("silence_duration_ms", 400))
                );

        if (enableServerVad) {
            logger.info("Sending event (VAD):\n" + eventVad.toString(2));
            client.send(eventVad.toString());
        } else {
            logger.info("Sending event (Manual):\n" + eventNoVad.toString(2));
            client.send(eventNoVad.toString());
        }
    }

    /** 发送音频文件流 */
    private static void sendAudio(String localAudioPath) throws Exception {
        Thread.sleep(3000); // 等会话准备
        byte[] allBytes = Files.readAllBytes(Paths.get(localAudioPath));
        logger.info("文件读取开始");

        int offset = 0;
        while (isRunning.get() && offset < allBytes.length) {
            int chunkSize = Math.min(3200, allBytes.length - offset);
            byte[] chunk = new byte[chunkSize];
            System.arraycopy(allBytes, offset, chunk, 0, chunkSize);
            offset += chunkSize;

            if (client != null && client.isOpen()) {
                String encoded = Base64.getEncoder().encodeToString(chunk);
                JSONObject eventd = new JSONObject()
                        .put("event_id", "event_" + System.currentTimeMillis())
                        .put("type", "input_audio_buffer.append")
                        .put("audio", encoded);

                client.send(eventd.toString());
                logger.info("Sending audio event: " + eventd.getString("event_id"));
            } else {
                break; // 避免在断开后继续发送
            }

            Thread.sleep(100); // 模拟实时发送
        }

        logger.info("文件读取完毕");

        if (client != null && client.isOpen()) {
            // 非 VAD 模式下需要 commit
            if (!enableServerVad) {
                JSONObject commitEvent = new JSONObject()
                        .put("event_id", "event_789")
                        .put("type", "input_audio_buffer.commit");
                client.send(commitEvent.toString());
                logger.info("Sent commit event for manual mode.");
            }

            JSONObject finishEvent = new JSONObject()
                    .put("event_id", "event_987")
                    .put("type", "session.finish");
            client.send(finishEvent.toString());
            logger.info("Sent finish event.");
        }
    }

    /** 初始化日志 */
    private static void initLogger() {
        logger.setLevel(Level.ALL);
        Logger rootLogger = Logger.getLogger("");
        for (Handler h : rootLogger.getHandlers()) {
            rootLogger.removeHandler(h);
        }

        Handler consoleHandler = new ConsoleHandler();
        consoleHandler.setLevel(Level.ALL);
        consoleHandler.setFormatter(new SimpleFormatter());
        logger.addHandler(consoleHandler);
    }
}