跳转到主要内容

​
产品简介

本接口提供基于 WebSocket 的双向流式 ASR 能力，适合实时发送音频分片并持续接收识别结果。

​
核心特性

  • 支持实时音频流输入
  • 支持增量文本输出与最终结果输出
  • 支持服务端 VAD 语音活动检测
  • 支持常见音频格式参数配置
  • 适合实时对话、语音助手、会议字幕等场景

​
接入方式总览

能力WebSocket 双向流式
音频输入流式分片
结果返回流式增量 + 完成事件
连接方式WebSocket
是否保持会话是
典型端前端 / 设备端

​
服务地址

协议环境地址说明
WebSocket正式环境wss://api.stepfun.com/v1/realtime/asr/stream双向实时流
如需基于 HTTP + SSE 一次性提交音频并接收流式识别结果，请参考 语音识别（流式返回文本）。

​
Websocket 协议接口

​
时序图

服务端 vad 开启时： 服务端 vad 未开启时：

​
鉴权参数

参数名必填描述示例
Authorization是认证令牌Bearer {token}

​
客户端消息类型

​
会话更新消息 (session.update)

用于更新会话配置，包括音频格式、转录参数等。 请求示例： 
{
  "event_id": "event_123",
  "type": "session.update",
  "session": {
    "audio": {
      "input": {
        "format": {
          "type": "pcm",
          "codec": "pcm_s16le",
          "rate": 16000,
          "bits": 16,
          "channel": 1
        },
        "transcription": {
          "model": "step-asr-1.1-stream",
          "language": "zh",
          "prompt": "请记录下你所听到的语音内容。",
          "full_rerun_on_commit": true,
          "enable_itn": true
        },
        "turn_detection": {
          "type": "server_vad",
          "silence_duration_ms": 800,
          "threshold": 0.5
        }
      }
    }
  }
}
参数路径类型描述示例值
event_idstring当前消息事件 ID"event_123"
typestring消息类型，固定为 session.update"session.update"
session.audio.input.format.typestring音频容器格式，支持 pcm、ogg"pcm"
session.audio.input.format.codecstring音频编码格式；当 type=pcm 时传 pcm_s16le"pcm_s16le"
session.audio.input.format.rateinteger音频采样率16000
session.audio.input.format.bitsinteger音频位深16
session.audio.input.format.channelinteger音频通道数1
session.audio.input.transcription.modelstring转录模型名称，支持 step-asr-1.1-stream"step-asr-1.1-stream"
session.audio.input.transcription.languagestring识别语言"zh"
session.audio.input.transcription.promptstring提示词，用于补充上下文或专业术语"请记录语音内容。"
session.audio.input.transcription.full_rerun_on_commitboolean是否在提交后进行二遍识别纠错，默认 falsetrue
session.audio.input.transcription.enable_itnboolean是否开启 ITN 文本规范化true
session.audio.input.turn_detection.typestring语音活动检测类型，支持 server_vad"server_vad"
session.audio.input.turn_detection.silence_duration_msinteger静音阈值，超过该时长后认为一句话结束800
session.audio.input.turn_detection.thresholdnumberVAD 检测阈值，值越大越严格0.5
补充说明：
  • 当前支持 step-asr-1.1-stream。
  • 如果不传 turn_detection.type=server_vad，服务端不会自动做 VAD。
  • 这时客户端需要主动发送 input_audio_buffer.commit。

​
音频数据追加消息 (input_audio_buffer.append)

发送音频数据进行实时识别。 请求示例： 
{
  "event_id": "event_124",
  "type": "input_audio_buffer.append",
  "audio": "base64_encoded_audio_data"
}
字段类型必需描述
event_idstring是事件唯一标识
audiostring是base64 编码的音频数据（WAV 格式）

​
音频缓冲区提交消息 (input_audio_buffer.commit)

仅在关闭了 server_vad 时，才需要提交该消息，是指要求服务端提交音频缓冲区，触发转录处理 
{
  "event_id": "event_125",
  "type": "input_audio_buffer.commit"
}

​
字段说明

字段类型必需描述
event_idstring是事件唯一标识

​
服务端消息类型

​
会话创建确认 (session.created)

确认会话创建成功。 
{
    "event_id": "319612d9-aede-4456-a1fd-bb9c21493cd9",
    "type": "session.created",
    "meta": {
        "session_id": "test_trace_1766470129914296764",
        "timestamp": 1766468589040
    },
    "session": {
        "audio": {
            "input": {
                "transcription": {
                    "language": "zh"
                },
                "format": {
                    "type": "pcm",
                    "codec": "pcm_s16le",
                    "rate": 16000,
                    "bits": 16,
                    "channel": 1
                },
                "turn_detection": {
                    "type": "server_vad",
                    "silence_duration_ms": 800
                }
            }
        }
    }
}

​
会话更新确认 (session.updated)

确认会话配置更新成功。 
{
    "event_id": "319612d9-aede-4456-a1fd-bb9c21493cd9",
    "type": "session.updated",
    "meta": {
        "session_id": "test_trace_1766470129914296764",
        "timestamp": 1766468589040
    },
    "session": {
        "audio": {
            "input": {
                "transcription": {
                    "language": "zh"
                },
                "format": {
                    "type": "pcm",
                    "codec": "pcm_s16le",
                    "rate": 16000,
                    "bits": 16,
                    "channel": 1
                },
                "turn_detection": {
                    "type": "server_vad",
                    "silence_duration_ms": 800
                }
            }
        }
    }
}

​
语音开始事件 (input_audio_buffer.speech_started)

仅在开启了 server_vad 时才会返回该事件，指服务端检测到语音开始。 
{
    "event_id": "319612d9-aede-4456-a1fd-bb9c21493cd9",
    "type": "input_audio_buffer.speech_started",
    "meta": {
        "session_id": "test_trace_1766470129914296764",
        "timestamp": 1766470145337
    },
    "audio_start_ms": 15240,
    "item_id": "item_26cbd6a7-16e8-44c9-b6b4-d4d3b3c87b41"
}

​
语音结束事件 (input_audio_buffer.speech_stopped)

仅在开启了 server_vad 时才会返回该事件，指服务端检测到语音结束。 
{
    "event_id": "406d719a-3392-4ca4-88b3-9f12d8189b74",
    "type": "input_audio_buffer.speech_stopped",
    "meta": {
        "session_id": "test_trace_1766470129914296764",
        "timestamp": 1766470143512
    },
    "audio_start_ms": 13480,
    "item_id": "item_8228b4a6-f127-4a60-8f33-20fcb7d9ff7d"
}

​
音频缓冲区提交确认 (input_audio_buffer.committed)

确认音频缓冲区已提交。 
{
  "event_id": "event_xxx",
  "type": "input_audio_buffer.committed",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "item_id": "item_xxx",
  "previous_item_id": "item_yyy"
}

​
对话项创建事件 (conversation.item.created)

新的对话项（转录结果）已创建。 
{
  "event_id": "event_xxx",
  "type": "conversation.item.created",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "previous_item_id": "item_yyy",
  "item": {
    "id": "item_xxx",
    "object": "realtime.item",
    "type": "message",
    "status": "in_progress",
    "role": "user",
    "content": [
      {
        "type": "input_audio"
      }
    ]
  }
}

​
转录增量事件 (conversation.item.input_audio_transcription.delta)

返回转录增量结果（流式输出）。 
{
  "event_id": "event_xxx",
  "type": "conversation.item.input_audio_transcription.delta",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "item_id": "item_xxx",
  "content_index": 0,
  "text": "你好",
  "start_time": 0,
  "end_time": 500
}

​
字段说明

字段类型描述
item_idstring对话项 ID
content_indexint内容索引
textstring增量转录文本
start_timeint64开始时间（毫秒）
end_timeint64结束时间（毫秒）

​
转录完成事件 (conversation.item.input_audio_transcription.completed)

返回完整转录结果。 
{
  "event_id": "event_xxx",
  "type": "conversation.item.input_audio_transcription.completed",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "item_id": "item_xxx",
  "content_index": 0,
  "transcript": "你好，世界",
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 10,
    "total_tokens": 10
  }
}

​
字段说明

字段类型描述
item_idstring对话项 ID
content_indexint内容索引
transcriptstring完整转录文本
usageobject使用统计信息

​
错误消息 (error)

返回错误信息。 
{
  "event_id": "event_xxx",
  "type": "error",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_value",
    "message": "错误描述",
    "param": "audio",
    "event_id": "event_xxx"
  }
}

​
错误类型

类型描述
invalid_request_error请求参数错误
internal_error服务器内部错误
risk内容安全风险

​
错误码

错误码描述
invalid_value无效参数值
missing_param缺少必需参数
internal_error内部错误
max_idle_timeout空闲超时
pong_timeout心跳超时
risk_blocked内容被拦截

​
错误处理

​
常见错误类型

  • invalid_request_error: 请求参数错误
  • internal_error: 服务器内部错误
  • risk: 内容安全风险

​
故障排除

  1. 连接失败: 检查服务是否启动，端口是否正确
  2. 音频无识别结果: 确认音频格式、编码和质量
  3. 识别准确性低: 尝试使用系统提示词或更换模型
  4. 延迟过高: 减少音频分块大小或使用轻量级模型