跳到主要内容

实时​ A​SR​（WebSocket）

实时​ A​SR ​通过​ WebSocket ​流式​传输​音频，​并​在​您​说话​时​返​回​转录​结果​——​在​音频​仍​在​传输​时​返​回​临时​的​**​部分​（partial）结果，​然后​按话​语返​回权威​的最​终​（final）​**​结果。​可用​于​实时​字幕、​会议​转录​和​语音界面。

如​需​一​次​性​转录​完整​的​音频​文件，​请​改用批量​ A​SR ​端点。

端点​

wss://api.shisa.ai/ws/asr/realtime

在​ WebSocket ​握​手​期间，​使用​您​的​ A​SR bearer ​令牌​进行​认证​:

Authorization: Bearer YOUR_API_KEY
需要实时访问权限

您​的​ A​PI 密钥​需要​对​ shisa/asr-realtime ​服务​具有​明确​的​访问​权限。​对​批量​ A​SR、​聊天、​翻译​或​ TTS ​的​访问​权限不​会授予实时​ A​S​R ​的​访问​权限。​如果​您​的​密钥​使用​服务​允许列表，​请​将​ shisa/asr-realtime 添​加到​其中​——否​则​握手​将​被​拒绝。

仅限服务器端

实时​ A​SR ​专为​后​端​使用​而​设计。​请​将​ A​PI ​密钥​保存在​服务器​端:​将​音频​从​浏览器​中​继​到​您​自己​的​服务器，​再​从​那​里​连接​到​ S​hi​sa。

工作​原理​

  1. 使用​ Authorization ​标头​打​开​到​端点​的​ WebSocket。
  2. 发送​一​条 session.update ​消息​以​设置音频​格式​和​语言。
  3. 等​待 session.created。
  4. 将​原始​音​频​作为​ base6​4 ​的​ input_audio.append ​消息​进行​流式​传输​（每​个​块 50–​250 ms ​是​不错​的​起点）。
  5. 将​ asr.partial_result ​显示​为​实时​临时​文本​;​当 asr.final_result ​到​达时​将​其​替换。
  6. 完成​后​发送​ session.close。

音频​要求​

发送​原始 PCM​——​不​使用​容器、​不压​缩:

属性值
编码pcm_s16le（有​符号​ 16​ ​位​小端）
采样率16000 Hz
声道1（单声道）
块间​隔建议​ 50–​250 ms​（示例​使用​ 100 ms）

发送​前请​在​客户​端​进行​重​采样​和​降混。​请​勿​发送​ WAV​ 头、​Ogg、​MP3、​data U​RL、​浮点​ PCM ​或​立体​声​音频。

客户​端​消息​

session.update​

在​发送​任何​音频​之前，​务必​发送​一​条 session.update。​固定​语言​的​会话​是​最​简单​的​选项​:

{
  "type": "session.update",
  "session": {
    "input_audio_format": "pcm_s16le",
    "sample_rate": 16000,
    "channels": 1,
    "language": "ja"
  }
}
字段是否​必​需值备​注
input_audio_format是pcm_s16le原始​有​符号​ 16​ ​位​小端​ P​CM。
sample_rate是16000发送​前​重采样​到​ 1​6 k​Hz。
channels是1仅​限单​声道。​请​先​降​混立体声。
language是ja、en、zh、auto已​知语言时​使用​固定值。​自动​语​言识别​使用​ auto（见​下文）。
default_language仅​ auto 时ja、en、zh检测​不​确定​时​的​回退值。
language_detection_mode仅​ auto 时session、utterancesession ​只​检测​一​次​;utterance ​按​段​检测​（进阶​——见​下文）。

input_audio.append​

将​音频​块​作为​ base64 ​编码​的​ P​CM ​进行​流式​传输​:

{
  "type": "input_audio.append",
  "audio": "<base64 pcm_s16le bytes>"
}

session.close​

完成​后​正常​关闭​会​话​:

{ "type": "session.close" }

语​言识别​（可选）​

如果​您​事先​不​知道​说话​的​语言，​请​设置​ language: "auto"。​有​两​种​模式。

会​话​检测在​开始​附近​识别​一​次​语言，​并​在​整个​会话​中​使用​该​语言:

{
  "type": "session.update",
  "session": {
    "input_audio_format": "pcm_s16le",
    "sample_rate": 16000,
    "channels": 1,
    "language": "auto",
    "default_language": "en",
    "language_detection_mode": "session"
  }
}

会​话会​发出​ session.language_detecting，​然后​发出​一​条​包含​所​选 language ​的​ session.language_detected。

逐话​语​检测（language_detection_mode: "utterance"）​分别​检测​每​个​话语​的​语言，​这​对于​多语言​混合​的​音频​很​有​用。​它​会​为​每​个​话语​发出​ utterance.language_detected。​此​模式​必须​在​后端​启用​;如果​未​启用，​会话​将​返​回​带​有​ code: "invalid_config" ​的​ error——此​时请​回退​到​固定​语言​或​会话​检测。

当​检测​无法确信​地​选择​时，​它​会​回退​到​ default_language，​并且​事件​会​带​有​ source: "default" ​和​ reason（例如​ no_speech、short_utterance、inconclusive ​或​ timeout）。​请​始终​将​ asr.final_result.text 视​为​权威​结果​——​不​要​仅​凭​语言​事件​就​改写​转录​文本。

服务​事件​

所有​事件​都​是​ JSON ​文本​消息。​会话​创建​后，​每​个​事件​都​带​有​ session_id ​和​单调​递增​的​ seq。

session.created​

会话​已​被​接受​;​您​可以​开始​发送​音频:

{
  "type": "session.created",
  "session_id": "asr_sess_...",
  "seq": 1,
  "format": { "encoding": "pcm_s16le", "sample_rate": 16000, "channels": 1 }
}

语音边界​

speech_started ​和​ speech_stopped ​标记​每​个​话语​的​语音​活动​检测​（VAD）​端点:

{
  "type": "speech_started",
  "session_id": "asr_sess_...",
  "seq": 4,
  "utterance_id": "utt_0001",
  "audio_start_ms": 420
}
{
  "type": "speech_stopped",
  "session_id": "asr_sess_...",
  "seq": 9,
  "utterance_id": "utt_0001",
  "audio_start_ms": 420,
  "audio_end_ms": 2860,
  "reason": "vad_endpoint"
}

常见​的​停止​原因​有​ vad_endpoint、max_buffer ​和​ session_close。

asr.partial_result​

进行​中话语​的​临时​文本。​请​按 utterance_id ​显示​最​新​的​部分​结果，​替换​前​一​个​——​不​要​将​每​个​部分​结果​都​追加到​历史​记录​中:

{
  "type": "asr.partial_result",
  "session_id": "asr_sess_...",
  "seq": 7,
  "utterance_id": "utt_0001",
  "result_id": "utt_0001:p3",
  "text": "今日の会議は3時から",
  "is_final": false,
  "audio_start_ms": 420,
  "audio_end_ms": 2260
}

asr.final_result​

话语​的​权威​文本。​使用​ replaces 丢弃​您​正在​显示​的​临时​部分​结果​:

{
  "type": "asr.final_result",
  "session_id": "asr_sess_...",
  "seq": 12,
  "utterance_id": "utt_0001",
  "result_id": "utt_0001:final",
  "replaces": ["utt_0001:p1", "utt_0001:p2", "utt_0001:p3"],
  "replaces_audio_range_ms": [420, 2860],
  "text": "今日の会議は3時からです。",
  "is_final": true,
  "audio_start_ms": 420,
  "audio_end_ms": 2860
}

最​终​结果​是​异步​的，​可能​在​后续​语​音​事件​之后​到达。​非常长​的​话语​可能​会​被​拆分​为​带​有额​外 continuation_of ​和​ overlap_mode ​元​数据​的​续接​最​终​结果​;​显示时​只​显示​逻辑​上​的​ audio_start_ms–audio_end_ms ​范围。

session.usage​

用量​是​累积​的。​计费​使用​最新​的​事件。billable_duration ​以​整秒​为​单位​:

{
  "type": "session.usage",
  "session_id": "asr_sess_...",
  "seq": 20,
  "final": true,
  "usage": {
    "input_duration": 18.3036875,
    "billable_duration": 19,
    "utterance_count": 3,
    "final_result_count": 3,
    "status": "completed",
    "final": true
  }
}

error​

{
  "type": "error",
  "code": "finalization_failed",
  "message": "Finalization failed",
  "fatal": false,
  "session_id": "asr_sess_...",
  "seq": 18,
  "utterance_id": "utt_0002"
}

致命​（fatal）​错误​之后​会​关闭​连接。​非致命​的​话语​错误​则​允许​会​话​继续。

处理​转录​结果​

  • 以​ utterance_id ​为​键保存临时​文本。
  • 当​更新​的​ asr.partial_result ​到​达​时，​替换​当前​的​部分​结果。
  • 收到​ asr.final_result ​时，​移除​ replaces ​中​的​ I​D ​并​提交​最​终​文本。
  • 显示​时​忽​略空​的​最终​文本​（但​保留​用于​诊断）。
  • 切勿​将​ session.usage 渲染​为​转录​文本。

后续​步​骤​