转录文本与提交策略

概述

转录音频时，你将收到部分转录文本和已提交转录文本。

• 部分转录文本 - 转录过程中的临时结果
• 已提交转录文本 - 收到“提交”消息时发送的最终转录片段结果。一个会话可以有多条已提交转录文本。

提交的转录文本还可包含词级时间戳。仅当“包含时间戳”选项设为 true 时才会收到这些时间戳。

# Initialize the connection
connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeUrlOptions(
  model_id="scribe_v3_live",
  include_timestamps=True, # Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps
))

提交策略

通过 WebSocket 发送音频块时，可通过三种方式提交转录片段：手动提交、语音活动检测（VAD）或轮次预测。轮次预测仅适用于 Scribe v3 Live。

手动提交

使用手动提交策略时，你可以控制何时提交转录片段。这是默认使用的策略。提交一个片段会清除已处理的累计转录文本，并开始新片段，同时不会丢失上下文。建议每 20-30 秒提交一次，以降低延迟。即使不手动提交，模型也会在累计约 36 秒音频后自动提交。

为获得最佳效果，请在静音期间或轮次结束等其他合适时机提交。

await connection.send({
  "audio_base_64": audio_base_64,
  "sample_rate": 16000,
})
# When ready to finalize the segment
await connection.commit()

发送之前的文本上下文

发送音频进行转录时，你可以在第一个音频块中一并发送之前的文本上下文，帮助模型理解语音上下文。这在以下场景中很有用：

• 对话式 AI 用例中的智能体文本 - 帮助模型更轻松地理解对话上下文，从而生成更好的转录文本。
• 网络错误后重新连接 - 让模型以前文作为参考继续转录。
• 常规上下文信息 - 简短说明转录内容，有助于模型理解上下文。

await connection.send({
  "audio_base_64": audio_base_64,
  "previous_text": "The previous text context",
})

语音活动检测（VAD）

使用 VAD 策略时，转录引擎会自动检测语音和静音片段。达到静音阈值后，转录引擎会自动提交转录片段。

在客户端集成中转录麦克风音频时，建议使用 VAD 策略。

vad_silence_threshold_secs 可接受 0.192 至 3.0 秒。JavaScript 和 React SDK 仅接受 0.3 至 3.0。

import { Scribe, AudioFormat, CommitStrategy } from "@elevenlabs/client";
const connection = Scribe.connect({
  token: "sutkn_1234567890",
  modelId: "scribe_v3_live",
  audioFormat: AudioFormat.PCM_16000,
  commitStrategy: CommitStrategy.VAD,
  vadSilenceThresholdSecs: 1.5,
  vadThreshold: 0.4,
  minSpeechDurationMs: 100,
  minSilenceDurationMs: 100,
});

轮次预测

较短的 VAD 静音阈值可能会在说话人停顿时截断其发言，而较长的阈值会增加每次提交前的延迟。轮次预测会利用对话上下文，而不只依赖静音，来判断说话人是否已结束当前轮次。例如，来电者读电话号码到一半时停顿，就更不容易被截断。

Scribe v3 Live 会在每条 partial_transcript 消息中包含 turn_probability，即说话人已结束当前轮次的预估概率：

{
  "message_type": "partial_transcript",
  "text": "My phone number is 415",
  "turn_probability": 0.08
}

使用 commit_strategy=turn_prediction 时，当部分转录文本的 turn_probability 达到 0.9 或更高，服务器会提交当前片段。VAD 仍会启用，因此达到 vad_silence_threshold_secs 静音阈值时，服务器也会提交。VAD 参数（vad_silence_threshold_secs、vad_threshold、min_speech_duration_ms 和 min_silence_duration_ms）对轮次预测的作用与对 VAD 相同。

包括 Scribe v3 Live 在内的所有模型默认提交策略都是 manual。请显式设置 commit_strategy=turn_prediction 以启用轮次预测。

wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v3_live&audio_format=pcm_16000&commit_strategy=turn_prediction

当模型为 Scribe v3 Live 时，所有提交策略都会发送 turn_probability。使用 manual 策略时，你可以读取它来决定何时在自己的应用中提交。

过滤背景音频

设置 filter_background_audio=true 查询参数，可减少附近交谈等背景语音和环境噪声造成的误激活。启用过滤后，语音活动检测会使用经过调优、可忽略背景语音的模型；除非你自行设置，否则 vad_threshold 默认为 0.15。

过滤不会影响计费：所有流式传输的音频都会计费，包括被过滤器忽略的音频。

在静音期间保持连接

官方 SDK 不会因未收到消息而断开连接，因此大多数集成无需此设置。如果自己的 WebSocket 客户端，或中间的代理或负载均衡器，会在一段时间未收到帧时关闭连接，请在连接时传入可选的 keepalive_interval_ms 查询参数。这在长时间静音时很重要，例如通话中有 10-15 秒的停顿。服务器大约每隔一个间隔会发送一条保活 partial_transcript：如果当前片段没有未提交文本，则为空（text: ""）；否则会重复最新的部分文本。

• 接受介于 500 和 10000（毫秒）之间的整数。默认禁用；省略该参数即可保持现有行为。
• 超出范围或非整数值会导致服务器发送 invalid_request 错误并关闭连接。
• 保活由模型实际处理发送的静音音频驱动，而不是自由运行的计时器，因此也能确认转录路径仍然正常。
• 音频大约按 1 秒块处理，因此保活消息会按该节奏四舍五入后大约每个间隔到达一次（例如，1000 大约每秒触发一次，3000 大约每 3 秒一次）。由于服务器会在转录前缓冲最初约 2 秒音频，会话的首次保活大约在启动 2 秒后到达。请将间隔设为不超过读取超时的约三分之一，以留出余量。
• 仅当当前片段还没有未提交文本时，保活消息的 text 才为空。如果语音结束后、提交前发生停顿——在 filter_background_audio=true 或未提交的手动提交模式下最明显——保活消息会改为重复最新部分文本，因此不会清空临时文本。提交后，保活消息会恢复为空，直到新的语音到达。
• 适用于 commit_strategy=manual 和 commit_strategy=vad，也适用于 filter_background_audio=true。除已流式传输的音频外，不会影响计费。
• session_started 消息的 config 会回显 keepalive_interval_ms（禁用时为 null）。

将该参数添加到 WebSocket URL：

wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v3_live&commit_strategy=vad&keepalive_interval_ms=1000

支持的音频格式

最佳实践

音频质量

• 为兼顾音质和带宽，建议使用 16 kHz 采样率。
• 确保音频输入清晰，尽量减少背景噪声。
• 使用合适的麦克风增益，避免削波。
• 目前仅支持单声道音频。

音频块大小

• 为实现流畅传输，请发送时长为 0.1 - 1 秒的音频块。
• 较小的音频块延迟更低，但开销更大。
• 较大的音频块效率更高，但可能引入延迟。

后续步骤