跳到主要内容

实时​ 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 视​为​权威​结果​——​不​要​仅​凭​语言​事件​就​改写​转录​文本。

路​由​器​管理​的​翻译​（可选）​

路​由​器​可以​异步​翻译​每​个​非空​的asr.final_result。​您​的​密钥​必须​同时​拥有shisa/asr-realtime和shisa/translate访问​权限；​翻译​默​认关闭，​必须​为​当前​WebSocket​会话​显式​启用。

在session.update之后​发送：

{
  "type": "router.translation.update",
  "id": "translate-en",
  "enabled": true,
  "target_langs": ["en"]
}
字段是否​必​需说​明
enabled必​需boolean。​设为false可​禁用​翻译，​此​时​省​略​目标语言。
target_langs启用​时1​至​3​个​唯​一且​有效​的​语言​代码。
id可​选客户​端关联ID，​会​在​控制​响应​中​回显；​最​多​3​6​个​字符。
context可​选提供​给​每​次​翻译​的​上下文；​最​多​2,000​个​Un​icode​码点。
keywords可​选术​语表数​组；​最​多​20​项，​每​项​最​多​100​字节。

接受​更新​后​返回：

{
  "type": "router.translation.updated",
  "id": "translate-en",
  "enabled": true,
  "target_langs": ["en"]
}

无效​配置会​返​回router.translation.error，​例如：

{
  "type": "router.translation.error",
  "id": "translate-en",
  "code": "too_many_target_langs",
  "message": "At most 3 target languages are allowed"
}

配置错误代码​包括invalid_json、invalid_message_type、invalid_id、id_too_long、invalid_enabled、missing_target_langs、too_many_target_langs、duplicate_target_lang、invalid_target_lang、context_too_long、too_many_keywords、keyword_too_long、translation_access_denied和translation_service_unavailable。​其他​保留​的router.*消息​会​返​回router.error，​代码​为unknown_router_message或router_message_too_large。

源语言解析

对于​每​个​最​终​结果，​路由​器​按​以下​优先​级​采用​第一​个​有效​的​源语言：​(1​) asr.final_result.language，​(2​) ​最​新​的session.language_detected，(3) session.update.session.language中​的​固定​语言。​它​不​会​直接​使用​独立​的utterance.language_detected事件​进行​翻译。​如果​最​终​结果​到​达时​没有​已​知​的​有效​语言，​该​目标会​收到code: "source_language_unknown"的translation.error。

服务​事件​

所有​事件​都​是​ JSON ​文本​消息。​会话​创建​后，​AS​R ​后​端事件​带​有session_id和​单调​递增​的seq。​路由​器​生成​的router.*和translation.*事件​不​带​这些​字段；​请​通过source_result_id将​翻译​结果​和​错误​关联到​ AS​R ​最​终​结果。

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時からです。",
  "language": "ja",
  "is_final": true,
  "audio_start_ms": 420,
  "audio_end_ms": 2860
}

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

translation.final_result​

启用​翻译​后，​路由​器​会​为​每​个​可​翻译​的​ASR​最​终​结果​按目标语言各​发出​一​条​结果：

{
  "type": "translation.final_result",
  "utterance_id": "utt_0001",
  "source_result_id": "utt_0001:final",
  "source_text": "今日の会議は3時からです。",
  "text": "Today's meeting starts at 3 o'clock.",
  "source_lang": "ja",
  "target_lang": "en",
  "model": "shisa-v2.1-unphi4-14b"
}

请​通过source_result_id将​结果​附加到​产生​它​的​准确A​SR​最​终​结果。​翻译​是​异步​的，​多​个​目标语言​的​结果​可能​以​任意​顺序​到​达。model是​后​端响​应​报告​的​模型​ ID，​可能​与​翻译​请​求​使用​的​默认别​名shisa-ai/chotto不同。

translation.error​

某​个​目标翻​译​失败时会​发出​目标​专用​错误，​而​不​会​关闭A​SR​会​话：

{
  "type": "translation.error",
  "code": "source_language_unknown",
  "message": "Cannot translate ASR final result before source language is known",
  "utterance_id": "utt_0001",
  "source_result_id": "utt_0001:final",
  "target_lang": "en"
}

其他​常见​代码​包括same_source_target_lang、translation_access_denied、translation_service_unavailable、translation_rate_limited、translation_rate_limiter_unavailable、translation_failed和source_text_too_long。​空​的​最终​文本​不​会​被​翻译，​也​不​会​发出​翻译​结果​或​翻译​错误。

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 ​并​提交​最​终​文本。
  • 通过source_result_id关联译文，​不​要​假​设目标语言​结果​的​到达​顺序。
  • 显示​时​忽​略空​的​最终​文本​（但​保留​用于​诊断）。
  • 切勿​将​ session.usage 渲染​为​转录​文本。

后续​步​骤​