实时 ASR(WebSocket)
实时 ASR 通过 WebSocket 流式传输音频,并在您说话时返回转录结果——在音频仍在传输时返回临时的**部分(partial)结果,然后按话语返回权威的最终(final)**结果。可用于实时字幕、会议转录和语音界面。
如需一次性转录完整的音频文件,请改用批量 ASR 端点。
端点
wss://api.shisa.ai/ws/asr/realtime
在 WebSocket 握手期间,使用您的 ASR bearer 令牌进行认证:
Authorization: Bearer YOUR_API_KEY
实时 ASR 对正常授权的有效 API 密钥公开。如果您的密钥使用 allowedServices 允许列表,请包含 shisa/asr-realtime;deniedServices 仍然优先。默认限制为每个 API 密钥 3 个并发 WebSocket 会话。各个密钥可能配置了不同的限制。
实时 ASR 专为后端使用而设计。请将 API 密钥保存在服务器端:将音频从浏览器中继到您自己的服务器,再从那里连接到 Shisa。
工作原理
- 使用
Authorization标头打开到端点的 WebSocket。 - 发送一条
session.update消息以设置音频格式和语言。 - 等待
session.created。 - 将原始音频作为 base64 的
input_audio.append消息进行流式传输(每个块 50–250 ms 是不错的起点)。 - 将
asr.partial_result显示为实时临时文本;当asr.final_result到达时将其替换。 - 完成后发送
session.close。
音频要求
发送原始 PCM——不使用容器、不压缩:
| 属性 | 值 |
|---|---|
| 编码 | pcm_s16le(有符号 16 位小端) |
| 采样率 | 16000 Hz |
| 声道 | 1(单声道) |
| 块间隔 | 建议 50–250 ms(示例使用 100 ms) |
发送前请在客户端进行重采样和降混。请勿发送 WAV 头、Ogg、MP3、data URL、浮点 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 位小端 PCM。 |
sample_rate | 是 | 16000 | 发送前重采样到 16 kHz。 |
channels | 是 | 1 | 仅限单声道。请先降混立体声。 |
language | 是 | ja、en、zh、auto | 已知语言时使用固定值。自动语言识别使用 auto(见下文)。 |
default_language | 仅 auto 时 | ja、en、zh | 检测不确定时的回退值。 |
language_detection_mode | 仅 auto 时 | session、utterance | session 只检测一次;utterance 按段检测(进阶——见下文)。 |
hotwords | 否 | 字符串数组 | 用于最终处理的全局词汇;最多 50 项(与语言映射限制分开)。 |
hotwords_by_language | 否 | 对象或 null | 按已解析语言区分的最终处理词汇;最多 5 个键、每种语言 100 项、语言映射项总计 300 项。 |
热词
热词会将最终处理偏向您的词汇表——产品名称、术语和专有名词。请在初始 session.update 中配置一次;它们会应用于该 WebSocket 会话中的所有话语。如需更改,请关闭会话,并使用新的 session.update 开启新的 WebSocket 会话。典型的呼叫中心集成每次客户通话使用一个 WebSocket 会话,而不是每个对话轮次使用一个会话。
固定语言会话是最简单的设置:
{
"type": "session.update",
"session": {
"input_audio_format": "pcm_s16le",
"sample_rate": 16000,
"channels": 1,
"language": "ja",
"hotwords": ["シーサー", "Shisa AI"]
}
}
热词仅影响 asr.final_result。实时的 asr.partial_result 事件可能仍包含未修正的拼写;当最终结果到达时,请替换显示的部分文本。服务事件不会回显配置的值。
限制
全局 hotwords 列表和语言映射列表有各自独立的限制:
| 配置 | 限制 |
|---|---|
全局 hotwords | 50 项 |
| 语言键 | 5 |
| 每种语言的项数 | 100 |
| 语言映射项总计 | 300 |
| 每项长度 | 1–100 个 Unicode 字符 |
每个项在其列表内必须唯一(大小写不敏感),并包含 1–100 个 Unicode 字符(严格来说是 Unicode 标量值),且不含前导/尾随空白或控制字符。服务会拒绝无效配置,而不是修剪、规范化、截断或去重。
语言特定热词(进阶)
会话可以在单个初始 session.update 中组合全局回退热词和语言特定列表:
{
"type": "session.update",
"session": {
"input_audio_format": "pcm_s16le",
"sample_rate": 16000,
"channels": 1,
"language": "auto",
"default_language": "en",
"language_detection_mode": "utterance",
"hotwords": ["global fallback"],
"hotwords_by_language": {
"ja": ["シーサー"],
"en": ["Shisa AI"],
"zh": ["狮萨"]
}
}
}
在固定语言或 LID 解析后,非空的精确匹配映射列表优先;匹配列表缺失或为空时回退到 hotwords。键必须是精确的小写 ASCII 双字母代码;当前部署请使用规范的 ja、en 和 zh。
hotwords_by_language 的可用性可能取决于所选的部署。如果不可用,会话会返回 invalid_config 错误。在这种情况下,请使用全局 hotwords 字段或联系支持。
消息大小策略
路由器接受最大 65,536 字节的普通客户端消息。当初始 session.update 的唯一顶层 type 恰好为 session.update 时,其大小最多可达 524,288 字节;这是为了容纳 hotwords_by_language 等有界字段。限制适用于组装后的完整 WebSocket 消息的 UTF-8 线缆字节数。
超过 65,536 字节的其他客户端消息,或超过 524,288 字节的任何客户端消息,会以 1009 关闭且不会被转发。后端到客户端的消息仍限制为 65,536 字节。运维人员可能配置更严格的限制,因此请紧凑序列化,并将 1009 视为终止性的会话错误。
input_audio.append
将音频块作为 base64 编码的 PCM 进行流式传输:
{
"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、unsupported、queue_full、buffer_limit、session_close、shutdown、vad_error 或 lid_error)。请始终将 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,会在控制响应中回显;最多36个字符。 |
context | 可选 | 提供给每次翻译的上下文;最多2,000个Unicode码点。 |
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 文本消息。会话创建后,ASR 后端事件带有session_id和单调递增的seq。路由器生成的router.*和translation.*事件不带这些字段;请通过source_result_id将翻译结果和错误关联到 ASR 最终结果。
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、leading_context_ms 和 payload_audio_range_ms 的续接最终结果。audio_start_ms/audio_end_ms 表示逻辑话语范围;payload_audio_range_ms 包含发送给最终 ASR 的重叠上下文,leading_context_ms 是 audio_start_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将结果附加到产生它的准确ASR最终结果。翻译是异步的,多个目标语言的结果可能以任意顺序到达。model是后端响应报告的模型 ID,可能与翻译请求使用的默认别名shisa-ai/chotto不同。
translation.error
某个目标翻译失败时会发出目标专用错误,而不会关闭ASR会话:
{
"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 以整秒为单位。顶层 model 是用于会计/调试的、由部署选择的最终处理模型;客户端不选择实时部分结果引擎:
{
"type": "session.usage",
"session_id": "asr_sess_...",
"seq": 20,
"final": true,
"model": "shisa-ai/shisa-asr",
"usage": {
"input_duration": 18.3036875,
"billable_duration": 19,
"input_bytes": 585718,
"sample_rate": 16000,
"channels": 1,
"utterance_count": 3,
"final_result_count": 3,
"final_error_count": 0,
"final_no_speech_count": 0,
"partial_result_count": 17,
"error_count": 0,
"status": "completed",
"final": true
}
}
处理错误
正常会话在连接、流式传输和关闭过程中不会产生任何错误事件。当确实需要处理时,API 会返回明确的代码,并尽可能说明下一步操作。
错误可能出现在两个阶段:建立连接时,作为带有 error 对象的 HTTP 响应;或在 WebSocket 会话期间,作为 type: "error" 的 JSON 事件。
连接被拒绝时
如果升级未被接受,则不会创建 WebSocket。响应是普通的 HTTP 错误:
{
"error": {
"code": "service_access_denied",
"message": "Service access denied"
}
}
常见原因很容易解决:
| HTTP | 代码 | 处理方法 |
|---|---|---|
401 | auth_token_required | 发送 Authorization: Bearer <key> 头。 |
401 | invalid_token_format | 使用包含前缀的完整 shsk:... 密钥。 |
401 | invalid_token | 确认密钥当前有效。请参阅认证。 |
401 | legacy_api_key_rejected | 将旧版密钥替换为当前 API 密钥。 |
403 | service_access_denied | 将 shisa/asr-realtime 添加到密钥的 allowedServices,或从 deniedServices 中移除。 |
403 | ws_origin_denied | 从允许的来源连接,或在服务器端客户端中省略 Origin 头。 |
429 | rate_limited、service_rate_limited | 降低速度并带退避重试。请参阅速率限制。 |
429 | ws_connection_limit_exceeded | 关闭空闲会话或等待其中一个结束。各个密钥可能配置了不同的限制;错误响应体包含适用的 limit 和当前 active 计数。 |
有时服务会短暂无法接受新会话(例如容量变更或维护期间)。这些情况是暂时的并返回 503;请带退避重试。这不是您的请求造成的。
临时服务代码
| HTTP | 代码 | 含义 |
|---|---|---|
503 | auth_unavailable | API 密钥验证暂时不可用。 |
503 | rate_limiter_unavailable、service_rate_limiter_unavailable | 速率限制检查暂时不可用。 |
503 | ws_connection_quota_unavailable | 连接配额跟踪暂时不可用。 |
503 | backends_at_capacity、backend_unavailable | 当前没有可用的实时 ASR 容量。 |
503 | websocket_draining | 服务正在完成计划内重启,暂不接受新会话。 |
503 | service_rate_limit_policy_invalid | 密钥的速率限制配置需要服务端更新。原样重试无法解决,请联系支持。 |
会话期间
升级成功后,后端会转发 JSON error 事件。大多数仅针对单个话语,会话可以继续;只有 fatal: true 会结束会话。后端可能会新增代码,因此请防御性地处理未知的 code 值:
{
"type": "error",
"code": "finalization_failed",
"message": "Finalization failed",
"fatal": false,
"session_id": "asr_sess_...",
"seq": 18,
"utterance_id": "utt_0002"
}
| 代码 | 处理方法 |
|---|---|
invalid_json、invalid_state | 检查消息顺序:在音频之前只发送一条 session.update,并使用已知的消息类型。 |
invalid_audio | 发送 16 kHz 单声道的原始 pcm_s16le;不要发送头部或压缩音频。 |
invalid_config | 检查所选的语音/LID 模式,并根据文档中的数量、长度、唯一性和字符规则验证热词。如果部署不支持 hotwords_by_language,请使用全局 hotwords 或联系支持。 |
frame_too_large | 发送更小的单条消息或音频块。 |
limit_exceeded | 已达到会话、缓冲区、识别积压或队列限制。视情况停止或关闭当前会话,然后带退避重试。如果持续出现,请联系支持。 |
finalization_timeout、finalization_cancelled、finalization_failed | 重试该话语。如果持续出现,请联系支持。 |
service_error | 临时的服务端问题。请重试;如果持续存在,请联系支持。 |
fatal: true | 此事件后会话结束。请重新连接并继续。 |
连接关闭行为
- 连接被拒绝时是普通 HTTP 响应;不会创建 WebSocket。
- 语言特定热词配置无效时,会产生
invalid_config事件,随后以1008关闭。 - 超过 65,536 字节的客户端消息会以
1009关闭;初始顶层session.update最多可使用 524,288 字节。 - 致命的会话内错误之后会跟随关闭帧。
- 记录关闭代码和原因,并在遇到暂时的容量、后端或网络状况时带退避重连。
处理转录结果
- 以
utterance_id为键保存临时文本。 - 当更新的
asr.partial_result到达时,替换当前的部分结果。 - 收到
asr.final_result时,移除replaces中的 ID 并提交最终文本。 - 通过
source_result_id关联译文,不要假设目标语言结果的到达顺序。 - 显示时忽略空的最终文本(但保留用于诊断)。
- 切勿将
session.usage渲染为转录文本。
后续步骤
- 使用批量 ASR 端点转录完整文件。
- 在音频与语言中查阅支持的格式和语言。
- 在定价中了解用量如何计费。