Messages
语音识别
语音识别 WebSocket (ASR)
基于 WebSocket 的实时 ASR 识别协议参考
WSS
Documentation Index
Fetch the complete documentation index at: https://docs.senseaudio.cn/llms.txt
Use this file to discover all available pages before exploring further.
说明
基于 WebSocket 的流式语音转文字接口,支持边录边转的实时交互,适用于实时字幕、语音助手、跨语言翻译、语音听写等低延迟场景。通信包含 JSON 控制消息与二进制音频消息两类。- 接入地址:
wss://api.senseaudio.cn/ws/v1/audio/transcriptions - 鉴权方式:Bearer Token,格式
Authorization: Bearer SENSEAUDIO_API_KEY - 音频格式:PCM signed 16-bit little-endian,采样率 16000Hz,单声道
- 模型参数:目前仅支持
senseaudio-asr-deepthink-1.5-260319 - 计费单位:按音频时长计费,详见 计费说明
- 离线转写:文件批量转写请使用 语音识别转写
请求头 (Request Headers)
| 参数名 | 必填 | 说明 | 示例 |
|---|---|---|---|
| Authorization | 是 | 鉴权 Token。格式:Bearer SENSEAUDIO_API_KEY | Bearer sk-123456… |
通信流程
客户端事件
1. task_start - 开始任务
客户端发送task_start 事件配置参数。服务端返回 task_started 后方可开始推送二进制音频帧。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| event | string | 是 | 固定值:task_start |
| model | string | 是 | 模型名称,目前仅支持 senseaudio-asr-deepthink-1.5-260319 |
| audio_setting | object | 是 | 音频参数设置,见下文详情 |
| vad_setting | object | 否 | VAD(语音活动检测)设置,见下文详情 |
| transcription_setting | object | 否 | 识别相关设置,见下文详情 |
audio_setting
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| sample_rate | int | 是 | 采样率,目前仅支持 16000 |
| channel | int | 是 | 声道数,目前仅支持 1(单声道) |
| format | string | 是 | 音频格式,目前仅支持 pcm |
vad_setting(可选)
| 参数名 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| silence_duration | int | 静音切分阈值 (ms) | 500 |
| min_speech_duration | int | 最小语音时长 (ms) | 300 |
| soft_max_duration | int | 软超时时长 (ms) | 15000 |
| hard_max_duration | int | 硬超时时长 (ms) | 30000 |
| soft_silence_duration | int | 软超时后的静音阈值 (ms) | 300 |
| threshold | float | VAD 能量阈值 (0.0 - 1.0) | 0.5 |
transcription_setting(可选)
| 参数名 | 类型 | 说明 | 示例 |
|---|---|---|---|
| target_language | string | 目标语言代码(详见下表) | en, zh |
| recognize_mode | string | 识别模式 | auto(默认)、record_only(仅识别不执行指令) |
target_language)
| 代码 | 语言 | 代码 | 语言 | 代码 | 语言 |
|---|---|---|---|---|---|
ar | Arabic | yue | Cantonese | zh | Chinese |
nl | Dutch | en | English | fr | French |
de | German | id | Indonesian | it | Italian |
ja | Japanese | ko | Korean | ms | Malay |
pt | Portuguese | ru | Russian | es | Spanish |
th | Thai | tr | Turkish | ur | Urdu |
vi | Vietnamese |
| 参数名 | 类型 | 说明 |
|---|---|---|
| event | string | 事件类型 |
| session_id | string | 会话 ID |
| trace_id | string | 链路追踪 ID |
| base_resp | object | 请求状态信息 |
| base_resp.status_code | int | 状态码 |
| base_resp.status_msg | string | 状态详情 |
2. 音频流传输(Binary Message)
客户端持续发送二进制音频数据,无需额外封装。- 格式要求:PCM signed 16-bit little-endian,16kHz,单声道。
- 建议分片:每片约 100ms(3200 字节)发送,便于模拟实时流。
- 断句机制:服务端通过 VAD 自动断句,每识别完一句话会返回一次
result_final。
result_final)
3. task_finish - 结束任务
客户端发送task_finish 事件通知音频发送完毕。服务端处理剩余音频后返回 task_finished 并关闭连接。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| event | string | 是 | 固定值:task_finish |
服务端事件
connected_success - 连接建立成功
初次请求接口时,表示 WebSocket 连接建立成功。task_started - 任务已开始
标志任务已成功开始,客户端可以开始推送音频帧。result_final - 识别结果
每完成一句断句返回一次,data 中包含识别文本及时间戳等信息。
| 参数名 | 类型 | 说明 |
|---|---|---|
| event | string | 事件类型 |
| session_id | string | 会话 ID |
| trace_id | string | 链路追踪 ID |
| data.text | string | 识别结果文本 |
| data.is_final | boolean | 识别是否结束 |
| data.segment_id | int | 分句序号 |
| data.timestamp_end | int64 | 该句结束时间(毫秒时间戳) |
| base_resp | object | 请求状态信息 |
task_finished - 任务已结束
标志任务已结束,WebSocket 连接即将关闭。task_failed - 任务失败
标志任务失败,base_resp.status_msg 中包含错误信息,服务端可能随即关闭连接。
使用示例
请将示例代码中的SENSEAUDIO_API_KEY 和 AUDIO_FILE 替换为实际值。
- Python
- Go
- Node.js
依赖: pip install websockets
错误码说明
| 状态码 | 说明 | 解决方案 |
|---|---|---|
| 0 | 成功 | - |
| 2013 | 缺少必填参数 | 检查 task_start 是否携带了 model 等必填字段 |
注意事项
- 消息类型区分:控制消息必须用文本帧发送 JSON,音频帧必须用二进制帧发送;混用会导致服务端解析失败。
- 事件发送顺序:必须按
连接 → task_start → 音频帧 → task_finish顺序发送;仅在收到task_started后才可发送音频。 - 音频参数:当前仅支持 16kHz / 16-bit / 单声道 PCM;若录音源采样率不同,需在客户端重采样。
- 实时流节奏:建议每片约 100ms(3200 字节)发送,避免过快占满缓冲或过慢导致 VAD 误触发。
- 连接关闭:收到
task_finished或task_failed后服务端会关闭连接,客户端应及时回收资源。
相关资源
离线转写 API
基于 HTTP 的文件识别接口。
WebSocket 实时识别指南
WebSocket ASR 的应用场景与接入最佳实践。
ASR 总览
语音识别能力与模型对比。
音频质量检测
离线音频噪声/可用性检测。
Messages