实时事件参考 | ElevenLabs Documentation

参考 · 列出通过 Realtime Speech to Text WebSocket 发送和接收的所有事件 API。

有关 API 及其选项的更多信息，请查看 Realtime Speech to Text API 的 API 参考文档。

committed_transcript 是每个分段稳定的最终事件。公开 API 不会单独发送 final_transcript 事件。

发送的事件

事件	说明	使用时机
`input_audio_chunk`	发送待转写的音频数据	持续流式传输音频时

使用 Scribe v3 Live 时，会话的第一个 input_audio_chunk 还可以包含一个术语库。

接收的事件

事件	说明	接收时机
`session_started`	确认连接并返回会话配置	WebSocket 连接建立后立即接收
`partial_transcript`	当前进行中分段的实时转写更新。后续的部分转写会替换先前内容。使用 `diarize=true` 时，包含带有 `speaker_id` 的草稿 `words`（识别前为 `null`）；说话人 ID 和时间戳可能会变化，未对齐的词语没有时间戳。还会作为保活消息发送——如果分段没有未提交文本，`text` 为空；否则重复最新的部分转写	音频处理期间、提交前。配置后，还会每隔约一个 `keepalive_interval_ms` 作为保活消息发送一次
`committed_transcript`	一个分段已确定的转写。这是该分段稳定的最终文本，不会再变化。使用 `diarize=true` 时，包含从 0 开始的 `segment_index`，且不会因说话人分离而延迟	提交后（手动提交或由 VAD 触发）
`diarized_transcript`	带说话人标签的转写，包含 `text`、`words` 和与已提交转写匹配的 `segment_index`。未确定的说话人为 `speaker_id: null`。参见说话人分离	每次已提交转写后按提交顺序接收，即使无法识别说话人也是如此。仅在 `diarize=true` 时接收
`speakers_merged`	表示 `from_speaker_id` 和 `to_speaker_id` 指向同一人。将部分转写和说话人分离转写中此前所有 `from_speaker_id` 替换为 `to_speaker_id`；按接收顺序应用链式合并。ID 永不复用	识别出两个说话人 ID 属于同一人时。仅在 `diarize=true` 时接收
`committed_transcript_with_timestamps`	包含词级时间戳和检测到的 `language_code` 的已提交转写	在已提交转写后发送。仅当查询参数包含 `include_timestamps=true` 或 `include_language_detection=true` 时接收
`committed_transcript_entities`	在已提交转写分段中检测到的实体及其字符偏移量	每次已提交转写后不久发送。仅当查询参数包含 `entity_detection` 时接收
`redacted_transcript`	已提交转写分段，其中已脱敏的实体会替换为标记，同时附带原始已提交文本	每次已提交转写后不久发送。仅当查询参数包含 `entity_redaction` 时接收
`edited_transcript`	已提交转写分段的编辑版本，同时附带原始已提交文本	每次已提交转写后不久发送。仅当查询参数包含 `transcript_edit` 时接收

语言代码

在查询参数中设置 include_language_detection=true，即可在 partial_transcript 和 committed_transcript_with_timestamps 事件中以 language_code 接收语音语言。

在 partial_transcript 中，始终会包含 language_code。在进行中的分段有足够语音以识别语言前（约 4 个词；对于中文、日文和泰文等不使用空格书写的语言，约 8 个字符），以及在连续多个部分转写中识别到相同语言前，其值均为 null。单个词等非常短的分段可能始终为 null；过短而无法识别语言的部分转写会重置连续部分转写计数。设置后，只有在连续多个部分转写中识别到新语言时才会更改，因此单次异常部分转写不会导致其切换。
没有口语文本的部分转写，例如只有标点符号时，language_code: null。
committed_transcript_with_timestamps 中的 language_code 是该分段的最终结果。如果它与最后一个部分转写不同，请使用已提交的值。该事件在 committed_transcript 后发送，因此在其到达前请显示部分转写的值。
如果连接时传入 language_code 或 secondary_languages，语言会在这些语言范围内由模型识别。如果没有提示，则根据转写文本检测。
未设置 include_language_detection=true 时，partial_transcript 事件没有 language_code 字段。

错误处理

如果发生错误，WebSocket 连接关闭前会返回错误消息。

错误类型	说明
`auth_error`	请求身份验证时出错。请仔细检查 API 密钥
`quota_exceeded`	已超出使用配额
`transcriber_error`	转写音频时出错。
`input_error`	处理音频块时出错。可能是输入格式或参数无效
`invalid_request`	连接参数被拒绝。请根据 API 参考文档检查查询参数
`error`	通用服务器错误。实体脱敏失败时也会发送，随后连接将关闭
`commit_throttled`	短时间内提交请求过多，提交操作受到限流
`unaccepted_terms`	尚未接受使用 Scribe 的服务条款。请在 ElevenLabs 控制台查看并接受条款和条件
`rate_limited`	已受到速率限制。请减少短时间内发出的请求数量
`queue_overflow`	处理队列已满。请减少短时间内发出的请求数量
`resource_exhausted`	服务器资源已满。请稍后重试
`session_time_limit_exceeded`	已达到最长会话时长。请开始新会话或升级订阅
`chunk_size_exceeded`	音频块过大。请减小块大小
`insufficient_audio_activity`	发送的有效音频不足，无法维持连接