跳转到主要内容
千问云 home page
开放平台文档
实时

Fun-ASR realtime WebSocket API

实时语音识别 WebSocket API

通过 WebSocket API，您可以使用任意编程语言接入 Fun-ASR 实时语音识别服务。如需更便捷的集成方式，请使用 Python SDK 或 Java SDK。 用户指南： 模型详情与选型建议请参见实时语音识别。

快速开始

示例代码

  • Node.js
  • C#
  • PHP
  • Go
安装依赖：
npm install ws
npm install uuid
示例代码：
const fs = require('fs');
const WebSocket = require('ws');
const { v4: uuidv4 } = require('uuid'); // 用于生成 UUID

// 若未配置环境变量，请将下行替换为您的 API Key：const apiKey = "sk-xxx"
const apiKey = process.env.DASHSCOPE_API_KEY;
const url = 'wss://dashscope.aliyuncs.com/api-ws/v1/inference/'; // WebSocket 服务地址
const audioFile = 'asr_example.wav'; // 替换为您的音频文件路径

// 生成 32 位随机 ID
const TASK_ID = uuidv4().replace(/-/g, '').slice(0, 32);

// 创建 WebSocket 客户端
const ws = new WebSocket(url, {
  headers: {
    Authorization: `Bearer ${apiKey}`
  }
});

let taskStarted = false; // 标识任务是否已启动

// 连接建立后发送 run-task 指令
ws.on('open', () => {
  console.log('已连接到服务器');
  sendRunTask();
});

// 处理接收到的消息
ws.on('message', (data) => {
  const message = JSON.parse(data);
  switch (message.header.event) {
    case 'task-started':
      console.log('任务已启动');
      taskStarted = true;
      sendAudioStream();
      break;
    case 'result-generated':
      console.log('识别结果:', message.payload.output.sentence.text);
      if (message.payload.usage) {
        console.log('任务计费时长（秒）:', message.payload.usage.duration);
      }
      break;
    case 'task-finished':
      console.log('任务已完成');
      ws.close();
      break;
    case 'task-failed':
      console.error('任务失败:', message.header.error_message);
      ws.close();
      break;
    default:
      console.log('未知事件:', message.header.event);
  }
});

// 若未收到 task-started 事件，关闭连接
ws.on('close', () => {
  if (!taskStarted) {
    console.error('任务未启动，正在关闭连接。');
  }
});

// 发送 run-task 指令
function sendRunTask() {
  const runTaskMessage = {
    header: {
      action: 'run-task',
      task_id: TASK_ID,
      streaming: 'duplex'
    },
    payload: {
      task_group: 'audio',
      task: 'asr',
      function: 'recognition',
      model: 'fun-asr-realtime',
      parameters: {
        sample_rate: 16000,
        format: 'wav'
      },
      input: {}
    }
  };
  ws.send(JSON.stringify(runTaskMessage));
}

// 发送音频流
function sendAudioStream() {
  const audioStream = fs.createReadStream(audioFile);
  let chunkCount = 0;

  function sendNextChunk() {
    const chunk = audioStream.read();
    if (chunk) {
      ws.send(chunk);
      chunkCount++;
      setTimeout(sendNextChunk, 100); // 每 100 毫秒发送一个分片
    }
  }

  audioStream.on('readable', () => {
    sendNextChunk();
  });

  audioStream.on('end', () => {
    console.log('音频流发送完毕');
    sendFinishTask();
  });

  audioStream.on('error', (err) => {
    console.error('读取音频文件出错:', err);
    ws.close();
  });
}

// 发送 finish-task 指令
function sendFinishTask() {
  const finishTaskMessage = {
    header: {
      action: 'finish-task',
      task_id: TASK_ID,
      streaming: 'duplex'
    },
    payload: {
      input: {}
    }
  };
  ws.send(JSON.stringify(finishTaskMessage));
}

// 处理错误
ws.on('error', (error) => {
  console.error('WebSocket 错误:', error);
});

核心概念

交互流程

客户端与服务器的交互流程如下：
交互时序图
1

建立连接

发送 WebSocket 连接请求，在请求头中携带认证信息。
2

启动任务

发送 run-task 指令，设置模型和音频参数。
3

确认启动

服务器返回 task-started 事件，此时可以开始发送音频。
4

流式传输音频

  • 持续发送二进制音频数据。
  • 服务器实时返回 result-generated 事件，包含中间结果和最终结果。
5

结束任务

音频发送完毕后，发送 finish-task 指令。
6

确认完成

服务器处理完剩余音频后，返回 task-finished 事件。
7

断开连接

任意一方关闭 WebSocket 连接。

音频要求

  • 声道：仅支持单声道。
  • 格式：支持 pcm、wav、mp3、opus、speex、aac、amr。WAV 文件须为 PCM 编码。Opus 和 Speex 文件须使用 Ogg 容器。amr 格式仅支持 AMR-NB。
  • 采样率：须与 run-task 指令中的 sample_rate 一致。

API 参考

连接端点

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

请求头

参数类型是否必选说明
Authorizationstring是认证令牌。格式：Bearer $DASHSCOPE_API_KEY。
user-agentstring否客户端标识。用于帮助服务器追踪请求来源。
X-DashScope-WorkSpacestring否千问云业务空间 ID。
X-DashScope-DataInspectionstring否是否开启数据合规检查。默认值：enable。仅在必要时关闭。

事件参考

客户端事件和服务端事件的详细参数说明请参见：

连接复用

WebSocket 连接支持跨任务复用。服务器返回 task-finished 事件后，可在同一连接上发送新的 run-task 指令启动下一个任务。
  1. 复用连接上的每个任务须使用唯一的 task_id。
  2. 任务失败时，服务器返回 task-failed 事件并关闭连接（无法复用）。
  3. 连接空闲超过 60 秒会自动超时断开。