Gemini Live WebSocket 接口文档

1. 模型说明

能力	Gemini Live 全双工实时多模态
低时延双向实时对话（全双工，可随时语音打断）	✅
多模态输入（文本 / 音频 / 视频）、输出（音频 / 文本）	✅
服务端自动 VAD（可关闭改由客户端上报活动边界）	✅
Function Calling / 代码执行 / Search as a Tool	✅
会话记忆（单会话内保留全部交互上下文）	✅
会话恢复（sessionResumption，客户端托管恢复）	✅
上下文窗口压缩（长会话）	✅
输入 / 输出音频转写	✅

2. 计费

2.1 官方计费

• Live API 在每一轮（turn）对全部上下文 token 计费，包含对话历史与系统指令（system instruction）；

• 用量通过服务端响应中的 usageMetadata 字段上报，客户端可据此监控与核对用量。

2.2 平台的计费项与用量

平台按帧结算：

• 每个含 usageMetadata 的服务端帧 = 该轮独立消耗，逐轮结算（Σ各轮 = 总账单）；

平台计费项（按 usageMetadata 明细的模态拆分，仅统计 count > 0 的项）：

chargeItemCode	对应用量维度（usageMetadata 字段）	中文名
in_token	promptTokensDetails[modality=TEXT]	输入文本 Token
in_token_audio	promptTokensDetails[modality=AUDIO]	输入音频 Token
in_token_image	promptTokensDetails[modality=IMAGE]	输入图片 Token
in_token_video	promptTokensDetails[modality=VIDEO]	输入视频 Token
out_token	candidatesTokensDetails[modality=TEXT] + thoughtsTokenCount	输出文本 Token（思考 Token 并入本项）
out_token_audio	candidatesTokensDetails[modality=AUDIO]	输出音频 Token
out_token_video	candidatesTokensDetails[modality=VIDEO]	输出视频 Token

拆分口径说明：

• 输入按 promptTokensDetails 的模态（TEXT / AUDIO / IMAGE / VIDEO）拆分，输出按 candidatesTokensDetails 的模态拆分；

• 思考 Token（thoughtsTokenCount）并入 out_token，不单列；

• 输出模态为 IMAGE 时折叠进 out_token（输出无独立图片计费项）；

• cachedContentTokenCount（缓存命中）暂不单列计费项；

• 接入方无需自行上报计费，usageMetadata（含 totalTokenCount）可作为对账参考。

3. 功能接口详情

3.1 全双工实时多模态 WebSocket

3.1.1 请求 url

wss://{YOUR_DOMAIN}/ws/api/v1/ai/{YOUR_ENDPOINT}/gemini/live

• {YOUR_DOMAIN}：平台分配的接入域名。

• {YOUR_ENDPOINT}：平台分配的接入端点标识（路径段）。

3.1.2 握手请求头参数

参数名	字段类型	是否必填	默认值	描述
Authorization	string	二选一	-	Bearer {{YOUR_AK}}

3.1.3 消息帧与通用字段

注：完整字段结构见官方文档

• 帧格式为纯 JSON 文本帧：每条 WebSocket Text Message 承载一个完整事件 JSON；音频数据经 Base64 编码后内嵌在 JSON 字段中（非二进制帧）。

• 客户端事件 JSON 顶层有且仅有一个协议字段（setup / clientContent / realtimeInput / toolResponse），服务端事件 JSON 顶层有且仅有一个协议字段（setupComplete / serverContent / toolCall / toolCallCancellation / usageMetadata / goAway / sessionResumptionUpdate / inputTranscription / outputTranscription）。收发双方按该顶层字段名分发处理（注意：本协议不使用 type 字段）。

• 平台合成事件使用顶层 event 字段，与上述协议事件区分，见 §3.3.10。

• 字段名采用官方 JSON 序列化的 lowerCamelCase（如 generationConfig、turnComplete、sessionResumption）；供应商参考文档部分表格使用 snake_case（如 generation_config、turn_complete、session_resumption），两者为同一字段的等价命名，下文统一使用 camelCase。

3.1.4 会话生命周期（建议时序）

客户端                                       平台
  │── WebSocket 建连（鉴权） ───────────────▶│
  │── setup（必须是建连后首帧） ────────────▶│
  │◀── setupComplete ───────────────────────│
  │── realtimeInput（音频 / 视频流式推流） ─▶│   （循环）
  │◀── serverContent（音频 / 文本增量返回） ─│
  │◀── usageMetadata / 转写 / toolCall 等 ──│
  │◀── goAway（连接即将终止预告） ───────────│
  │◀── session_closing（平台：实例即将下线） │
  │◀── 连接关闭                              │
  │◀── connection_closed_by_model（平台） ──│
  │── 新建连 + setup(sessionResumption.handle=上次newHandle) ▶│
  │◀── setupComplete（会话上下文已恢复） ────│

要点：

1. setup 必须是建连后首帧，且只发一次；应等待 setupComplete 后再发送其他事件。

2. 之后通过 realtimeInput 持续流式推送音频 / 视频；模型通过 serverContent 增量返回音频与文本；一轮结束时会有 generationComplete / turnComplete 标志。

3) 连接约 10 分钟到期：到期前约 30秒服务端下发 goAway；收到后应停止发送新请求帧并准备重连。

4) 实例维护等场景下，客户端可能先收到平台下发的 session_closing（见 §3.3.10.1），随后连接关闭。建议收到后重连，避免服务端中断。

1. 上游连接关闭（含正常到期与异常断开）时，平台会下发 connection_closed_by_model（见 §3.3.10.2）。

2. 断开后可恢复会话（客户端托管恢复）：在 setup 中启用 sessionResumption 后，服务端周期性下发 sessionResumptionUpdate；客户端保存其中 newHandle，重连时在新 setup.sessionResumption.handle 中回传即可恢复上下文。恢复须在 24 小时内完成，且恢复窗口约 10 分钟（超时状态被丢弃）。

3.1.5 请求示例（建连后发送 setup）

{
  "setup": {
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": {
          "prebuiltVoiceConfig": {
            "voiceName": "Charon"
          }
        }
      }
    },
    "systemInstruction": {
      "parts": [{ "text": "你是友好的语音助手，请用简体中文回答。" }]
    },
    "inputAudioTranscription": {},
    "outputAudioTranscription": {}
  }
}

3.1.6 响应示例（setupComplete）

{
  "setupComplete": {
    "sessionId": "session-xxxxxxxx"
  }
}

---

3.2 客户端事件（客户端 → 服务端）

客户端事件一览：

事件（顶层字段）	协议消息名	用途	方向
setup	BidiGenerateContentSetup	会话配置，必须为建连后首帧（仅发一次）	C → S
clientContent	BidiGenerateContentClientContent	增量内容更新（文本输入、上下文注入 / 恢复）	C → S
realtimeInput	BidiGenerateContentRealtimeInput	实时音视频流输入、活动边界信号	C → S
toolResponse	BidiGenerateContentToolResponse	回传 Function Calling 执行结果	C → S

以下各节「请求参数」指单帧 JSON 根对象字段。

3.2.1 setup（BidiGenerateContentSetup）

参数名	字段类型	是否必填	默认值	描述
setup	object	是	-	会话配置对象，整个会话期间生效，且仅能作为首帧发送一次
setup.generationConfig	object	否	-	生成参数配置
setup.generationConfig.responseModalities[]	string[]	否	-	输出模态，如 ["AUDIO"]；开启转写需包含 "TEXT"
setup.generationConfig.temperature	number	否	-	采样温度
setup.generationConfig.topP	number	否	-	nucleus sampling 参数
setup.generationConfig.topK	int	否	-	top-K 采样参数
setup.generationConfig.maxOutputTokens	int	否	-	最大输出 token 数
setup.generationConfig.candidateCount	int	否	-	候选回复数量
setup.generationConfig.presencePenalty	number	否	-	存在惩罚
setup.generationConfig.frequencyPenalty	number	否	-	频率惩罚
setup.generationConfig.speechConfig	object	否	-	语音（音色 / 语言）配置
setup.generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName	string	否	-	指定音色名
setup.systemInstruction	object	否	-	系统指令，parts 中仅应使用文本；只能在会话开始时设置，会话中可用 clientContent（role=system）追加更新
setup.tools[]	object[]	否	-	工具定义列表（函数声明使用 OpenAPI Schema 的子集：name / description / parameters / required）
setup.sessionResumption	object	否	-	会话恢复配置；若包含，服务端将周期性下发 sessionResumptionUpdate
setup.sessionResumption.handle	string	否	-	恢复句柄：新会话不填（或填 null）；重连续传时传入上次 sessionResumptionUpdate.newHandle
setup.sessionResumption.transparent	bool	否	-	透明模式；开启后 sessionResumptionUpdate 返回 lastConsumedClientMessageIndex，便于重连时重放未消费消息
setup.contextWindowCompression	object	否	-	上下文窗口压缩配置（长会话推荐开启，注意会丢失被压缩的早期历史）
setup.contextWindowCompression.triggerTokens	int	否	-	触发压缩的累计 token 阈值，取值 5,000 – 128,000
setup.contextWindowCompression.slidingWindow.targetTokens	int	否	-	压缩后目标窗口大小，取值 0 – 128,000
setup.realtimeInputConfig	object	否	-	实时输入处理配置
setup.realtimeInputConfig.automaticActivityDetection.disabled	bool	否	false	设为 true 关闭服务端自动 VAD，改由客户端发送 activityStart / activityEnd
setup.inputAudioTranscription	object	否	-	输入音频转写配置
setup.inputAudioTranscription.languageCodes[]	string[]	否	-	BCP-47 语言提示，如 "en-US"，可提升多语言识别质量
setup.inputAudioTranscription.customVocabulary[]	string[]	否	-	自定义词表（最多 1,000 条），偏置识别专有名词
setup.outputAudioTranscription	object	否	-	输出音频转写配置，字段同上
setup.proactivity	object	否	-	模型主动性配置（主动响应、忽略无关输入）
setup.safetySettings[]	object[]	否	-	安全设置列表
setup.labels	map\	否	-	用户自定义元数据标签，仅用于计费与报表（键 / 值 ≤ 63 字符）

注：generationConfig 中以下字段供应商不支持，请勿下发：responseLogprobs、responseMimeType、logprobs、responseSchema、stopSequences、routingConfig、audioTimestamp。

BidiGenerateContentSetup / GenerationConfig / Content 等复合类型的完整定义见官方文档：BidiGenerateContentSetup、GenerationConfig、Content。

3.2.2 clientContent（BidiGenerateContentClientContent）

参数名	字段类型	是否必填	默认值	描述
clientContent	object	是	-	增量内容更新对象，内容会无条件追加到对话历史并作为生成提示
clientContent.turns[]	object[]	否	-	追加到当前对话的内容；单轮为单条，多轮为完整历史 + 最新请求
clientContent.turns[].role	string	否	-	对话角色：user / model；会话中途更新系统指令可用 system
clientContent.turns[].parts[].text	string	否	-	文本内容
clientContent.turnComplete	bool	否	-	true 表示服务端应基于当前累积提示开始生成；false 表示等待后续消息

注：

1. 该事件会打断当前正在进行的生成；请勿用它回传函数结果（应使用 toolResponse），仅用于建立上下文或输入文本。

2. 会话中途更新系统指令：发送 role="system" 的文本内容并将 turnComplete 置为 true，更新后剩余会话持续生效。

{
  "clientContent": {
    "turns": [
      {
        "role": "user",
        "parts": [{ "text": "你好，请介绍一下你自己。" }]
      }
    ],
    "turnComplete": true
  }
}

3.2.3 realtimeInput（BidiGenerateContentRealtimeInput）

参数名	字段类型	是否必填	默认值	描述
realtimeInput	object	是	-	实时输入对象；可连续发送而不打断模型生成
realtimeInput.audio	object	否	-	实时音频块（Blob），构成实时音频输入流
realtimeInput.audio.data	string	否	-	Base64 编码的音频字节（16kHz / 16bit PCM / 小端序）
realtimeInput.audio.mimeType	string	否	-	固定为 "audio/pcm;rate=16000"
realtimeInput.video	object	否	-	实时视频帧（Blob），构成实时视频输入流
realtimeInput.video.data	string	否	-	Base64 编码的 JPEG 图片字节
realtimeInput.video.mimeType	string	否	-	固定为 "image/jpeg"
realtimeInput.text	string	否	-	实时文本输入流
realtimeInput.activityStart	object	否	-	用户活动开始信号（仅自动 VAD 关闭时可发送，无字段）
realtimeInput.activityEnd	object	否	-	用户活动结束信号（仅自动 VAD 关闭时可发送，无字段）
realtimeInput.audioStreamEnd	bool	否	-	音频流结束标志（如关麦）；仅自动 VAD 开启时使用，发送后可随时恢复推流
realtimeInput.mediaChunks[]	object	否	-	内联媒体块（Blob）

音频推流示例：

{
  "realtimeInput": {
    "audio": {
      "mimeType": "audio/pcm;rate=16000",
      "data": "BASE64_AUDIO_DATA"
    }
  }
}

视频帧推流示例：

{
  "realtimeInput": {
    "video": {
      "mimeType": "image/jpeg",
      "data": "BASE64_JPEG_DATA"
    }
  }
}

3.2.4 toolResponse（BidiGenerateContentToolResponse）

收到服务端 toolCall（见 §3.3.3）后，客户端执行本地函数并通过本事件回传结果，id 与请求侧配对。

参数名	字段类型	是否必填	默认值	描述
toolResponse	object	是	-	函数执行结果回传对象
toolResponse.functionResponses[]	object[]	是	-	函数响应列表，与 toolCall.functionCalls[] 按 id 配对
toolResponse.functionResponses[].id	string	否	-	对应函数调用的唯一 id，须与 toolCall 下发的一致
toolResponse.functionResponses[].name	string	否	-	函数名
toolResponse.functionResponses[].response	object	否	-	函数执行结果（对象形式）

{
  "toolResponse": {
    "functionResponses": [
      {
        "id": "function-call-001",
        "name": "get_weather",
        "response": {
          "output": { "temperature": 25, "unit": "°C", "condition": "晴" }
        }
      }
    ]
  }
}

3.3 服务端事件（服务端 → 客户端）

服务端事件一览：

事件（顶层字段）	协议消息名	用途	方向
setupComplete	BidiGenerateContentSetupComplete	setup 完成确认（应等待本事件后再发其他事件）	S → C
serverContent	BidiGenerateContentServerContent	模型生成内容（音频 / 文本增量、打断与轮次结束标志、转写等）	S → C
toolCall	BidiGenerateContentToolCall	请求客户端执行函数调用（Function Calling）	S → C
toolCallCancellation	BidiGenerateContentToolCallCancellation	用户打断导致此前下发的函数调用被取消	S → C
usageMetadata	UsageMetadata	本轮 token 用量上报（平台结算与对账依据，见 §2.2）	S → C
goAway	GoAway	连接即将终止预告（到期前约 60 秒，收到后准备重连）	S → C
sessionResumptionUpdate	SessionResumptionUpdate	会话恢复检查点更新（需 setup 启用 sessionResumption）	S → C
inputTranscription	BidiGenerateContentTranscription	输入音频转写文本（增量）	S → C
outputTranscription	BidiGenerateContentTranscription	输出音频转写文本（增量）	S → C
event（平台合成）	-	平台合成事件：session_closing / connection_closed_by_model，见 §3.3.10	S → C

服务端事件 JSON 顶层有且仅有一个协议字段，按顶层字段名分发处理（不使用 type 字段）。

各事件消息的官方定义统一见：Multimodal Live API Reference；下文涉及的 Content、GenerationConfig 等复合类型不再展开，直接给出官方跳转链接。

3.3.1 setupComplete（BidiGenerateContentSetupComplete）

参数名	字段类型	是否必返	描述
setupComplete	object	是	setup 处理完成确认；客户端应等待本事件后再发送其他事件
setupComplete.sessionId	string	是	本次会话的会话 id

3.3.2 serverContent（BidiGenerateContentServerContent）

模型对客户端消息的增量响应；内容尽快生成（非实时），客户端可缓冲后按实时节奏播放。

参数名	字段类型	是否必返	描述
serverContent	object	是	模型生成内容增量对象
serverContent.modelTurn	Content	否	模型本轮生成的内容；输出音频位于 parts[].inlineData.data（Base64，24kHz / 16-bit PCM）。Content 结构见 官方文档
serverContent.interrupted	bool	否	true 表示用户语音打断了当前生成；实时播放客户端应立即停止并清空播放队列
serverContent.generationComplete	bool	否	true 表示本轮生成完成；被打断的轮次无此标志（按 interrupted → turnComplete 收尾）
serverContent.turnComplete	bool	否	true 表示对话回合结束，服务端等待后续客户端消息才会开始下一轮；可与 modelTurn 同帧（该段内容为本轮最后一段）
serverContent.turnCompleteReason	string	否	回合结束原因枚举（安全拒绝 / 内容违规 / 需要更多输入等），见 官方枚举
serverContent.speechState	string	否	服务端语音检测状态变化：SPEECH（检测到语音）/ NON_SPEECH（无语音）
serverContent.interactionStatus	string	否	会话活动状态，恒与 turnComplete 同帧下发：IN_PROGRESS（仍在处理）/ IDLE（全部处理完成）
serverContent.inputTranscription	object	否	输入音频转写（text / finished），与模型轮次相互独立、无顺序保证
serverContent.outputTranscription	object	否	输出音频转写（text / finished），同上
serverContent.interimInputTranscription	object	否	用户说话过程中的低时延中间转写
serverContent.groundingMetadata	object	否	搜索接地（Search as a Tool）来源元数据，见 官方文档

3.3.3 toolCall（BidiGenerateContentToolCall）

参数名	字段类型	是否必返	描述
toolCall	object	是	函数调用请求对象
toolCall.functionCalls[]	object[]	是	待执行的函数调用列表；客户端执行后经 toolResponse 按 id 回传
toolCall.functionCalls[].id	string	否	函数调用唯一 id（与 toolResponse.functionResponses[].id 配对）
toolCall.functionCalls[].name	string	否	函数名（对应 setup.tools[] 中的声明）
toolCall.functionCalls[].args	object	否	函数入参（对象形式）

FunctionCall 完整定义见 官方文档。因用户打断而取消的调用通过 toolCallCancellation 通知（见 §3.3.4）。

3.3.4 toolCallCancellation（BidiGenerateContentToolCallCancellation）

参数名	字段类型	是否必返	描述
toolCallCancellation	object	是	函数调用取消通知（仅客户端打断服务端回合时出现）
toolCallCancellation.ids[]	string[]	是	被取消的函数调用 id 列表；已有副作用的调用客户端可尝试回滚

3.3.5 usageMetadata（UsageMetadata）

本轮 token 用量上报。平台计费口径见 §2.2：每个含 usageMetadata 的服务端帧 = 该轮独立消耗，Σ各轮 = 总账单。

参数名	字段类型	是否必返	描述
usageMetadata	object	是	用量对象（本字段帧即该轮结算依据）
usageMetadata.promptTokenCount	int	是	本轮输入 token 总数
usageMetadata.candidatesTokenCount	int	否	本轮输出 token 总数
usageMetadata.totalTokenCount	int	否	本轮 token 总数（对账参考）
usageMetadata.cachedContentTokenCount	int	否	缓存命中 token 数
usageMetadata.thoughtsTokenCount	int	否	思考 token 数（平台并入 out_token 计费）
usageMetadata.promptTokensDetails[]	object[]	否	输入按模态（TEXT / AUDIO / IMAGE / VIDEO）拆分明细（modality + tokenCount）
usageMetadata.candidatesTokensDetails[]	object[]	否	输出按模态拆分明细（modality + tokenCount）

UsageMetadata 完整定义见 官方文档。

3.3.6 goAway（GoAway）

参数名	字段类型	是否必返	描述
goAway	object	是	连接即将终止预告
goAway.timeLeft	string	否	剩余连接时长（如 "60s"）；平台连接约 10 分钟到期，到期前约 60 秒下发。收到后停止发送新请求帧，并按 §3.1.4 重连（可携 sessionResumption.handle 恢复上下文）

GoAway 完整定义见 官方文档。

3.3.7 sessionResumptionUpdate（SessionResumptionUpdate）

参数名	字段类型	是否必返	描述
sessionResumptionUpdate	object	是	会话恢复检查点更新（需在 setup 中启用 sessionResumption）
sessionResumptionUpdate.newHandle	string	否	新的恢复句柄；客户端保存之，重连时回传 setup.sessionResumption.handle
sessionResumptionUpdate.resumable	bool	否	当前检查点是否可恢复；false 时 newHandle 不可用于恢复
sessionResumptionUpdate.lastConsumedClientMessageIndex	string	否	透明模式（transparent=true）下返回的已消费客户端消息索引，用于重连重放未消费消息

SessionResumptionUpdate 完整定义见 官方文档。

3.3.8 inputTranscription（BidiGenerateContentTranscription）

参数名	字段类型	是否必返	描述
inputTranscription	object	是	输入音频转写事件（增量；对齐输入音频语言）
inputTranscription.text	string	否	转写文本
inputTranscription.finished	bool	否	转写是否完成

3.3.9 outputTranscription（BidiGenerateContentTranscription）

字段结构与 §3.3.8 一致，为输出音频转写事件（对齐输出音频语言）。开启转写需 responseModalities 含 "TEXT"。

3.3.10 平台合成事件（顶层 event 字段）

平台在协议事件之外，使用顶层 event 字段下发平台合成事件，与协议事件字段互斥。

3.3.10.1 session_closing（实例即将下线）

参数名	字段类型	是否必返	描述
event	string	是	固定为 "session_closing"：平台实例即将下线（实例维护 / 生命周期到期等）

收到后应立即停止发送新请求帧，并按 §3.1.4 重新建连（可携 sessionResumption.handle 恢复上下文），避免服务端直接中断。帧示例：

{ "event": "session_closing" }

3.3.10.2 connection_closed_by_model（上游连接已关闭）

参数名	字段类型	是否必返	描述
event	string	是	固定为 "connection_closed_by_model"：上游模型连接已关闭（正常到期与异常断开均会下发）
code	int	是	关闭码：预期关闭（如到期）为 1000，非预期断开为 1011
reason	string	是	关闭原因说明（透传上游关闭描述）

收到后按 §3.1.4 重连并恢复会话。帧示例：

{ "event": "connection_closed_by_model", "code": 1000, "reason": "..." }

3.4 音频 / 视频格式与推流注意事项

输入音频

• 格式：原始 16-bit PCM、16000Hz、单声道、小端序；字节经 Base64 编码后放入 realtimeInput.audio.data；

• 分片建议 20 – 40 ms 一块，不要在发送前做明显缓冲（例如缓冲 1 秒再发）；

• 麦克风采集通常为 44.1kHz / 48kHz，发送前必须重采样至 16kHz；

• 关麦或暂停超过 1 秒（自动 VAD 开启时）：发送 realtimeInput.audioStreamEnd=true 冲刷服务端缓存的音频，随后可随时恢复推流。

输出音频

• 格式：原始 16-bit PCM、24000Hz、单声道、小端序，位于 serverContent.modelTurn.parts[].inlineData.data（Base64）；

• 服务端按块流式返回，客户端负责解码、缓冲与实时播放；收到 interrupted=true 时应立即停止并清空播放队列。

视频

• 逐帧 JPEG，建议 1 FPS、768x768 分辨率；模型按 1 FPS 处理（不适合分析高速变化的画面）；

• Base64 后放入 realtimeInput.video.data，mimeType 为 "image/jpeg"；

• 可在会话配置中设置 mediaResolution（low / medium / high）：低分辨率降低 token 消耗与时延，高分辨率提升细节识别。

VAD 与打断

• 默认由服务端自动 VAD；用户语音打断时，正在进行的生成被取消并丢弃，服务端下发 interrupted=true（未完成的函数调用通过 toolCallCancellation 取消）；

• 自定义活动检测：在 setup 中将 realtimeInputConfig.automaticActivityDetection.disabled 设为 true，由客户端在合适时机发送 activityStart / activityEnd（此配置下不发 audioStreamEnd，流中断以 activityEnd 标记）；

• 可在 setup 中开启 explicitVadSignal，显式接收服务端 VAD 信号事件。

会话时长与恢复

• WebSocket 连接约 10 分钟上限，到期前约 60 秒下发 goAway；

• 不开启压缩：纯音频会话约 15 分钟、含视频会话约 2 分钟（受 token 上限约束）；开启 contextWindowCompression 后可无限延长（注意：压缩会丢失早期对话历史）；

• 会话恢复：在 setup 中启用 sessionResumption；24 小时内可携 handle 恢复，恢复窗口约 10 分钟（超时状态被丢弃）；透明模式（transparent=true）下可按 lastConsumedClientMessageIndex 重放未消费的客户端消息；

• 需零数据保留的场景不要开启会话恢复（恢复依赖服务端缓存会话数据）。

语言与转写

• 建议显式指定音色与输出语言，并在系统指令中强调输出语言（如 RESPOND IN {OUTPUT_LANGUAGE}. YOU MUST RESPOND UNMISTAKABLY IN {OUTPUT_LANGUAGE}.）；

• 开启转写需 responseModalities 含 "TEXT"；开启转写会增加 token 消耗；

• customVocabulary 可提升产品名 / 专有名词的识别准确率（最多 1,000 条）；在系统指令中列词表不能达到同等效果。

限流与并发

• 每项目并发会话数、每分钟 token 数受供应商配额限制（不同供应商文档口径略有差异，以平台接入必读为准）。

平台侧断连

• 收到 session_closing（实例即将下线）或 connection_closed_by_model（上游连接关闭）后，停止发送新请求帧并按 §3.1.4 重连；