实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频AI 音视频互动方案API 参考更新 AI 对话 UpdateVoiceChat
复制全文
下载 pdf更新 AI 对话 UpdateVoiceChat
文档反馈
问问助手通过 StartVoiceChat 成功启动一个智能体任务后，你可以在对话进行中的任何时刻调用本接口发送实时任务指令或更新任务配置。
- 发送实时指令：
- 手动打断 AI：立即打断 AI当前的语音播报。
- 回传 Function Calling 的工具调用结果：向 LLM 回传 Function Calling 的工具调用结果。
- 手动触发 AI 响应：结束当前用户的语音输入，立即触发新一轮对话。
- 自定义语音播放：让 AI 主动播报一段指定的文本。
- 动态传入上下文：向 LLM 传入下一轮对话的背景信息（不立即回复）。
- 传入文本直接提问：通过文本直接向 AI 提问。
- 传入自定义文本让 AI 播报：传入一段自定义文本，让 AI 直接合成语音并播报，同时可传入自定义业务信息。
- 图片理解：向具备视觉能力的 LLM 传入图片。
- 动态传入情绪指令标签：注入指令标签，来控制 AI 下一轮回复播报的语气（如欢快、伤心）、语速和音量等。
- 暂停或恢复 AI 播报：随时暂停或恢复其音频播放，实现类似音乐播放器的暂停/继续效果。
- 更新任务配置（如TTS、LLM 等）：具体支持更新的配置项，以 Parameters 对象为准。更新配置不影响正在进行的回答，会在下一次提问的时候生效。
使用说明
- 调用方法：发送 HTTP(S) 请求时，你需要符合火山引擎规范。调用接口的请求结构、公共参数、签名机制、返回结构，参看如何调用 OpenAPI。
- 请求频率：单账号下 QPS 不得超过 60。
- 请求接入地址：仅支持 rtc.volcengineapi.com。
请求说明
- 请求方式：POST
- 请求地址：https://rtc.volcengineapi.com?Action=UpdateVoiceChat&Version=2025-06-01
请求参数
Query
Action String 必选示例值：UpdateVoiceChat
接口名称。当前 API 的名称为 UpdateVoiceChat。
Version String 必选示例值：2025-06-01
接口版本。当前 API 的版本为 2025-06-01。
Body
AppId String 必选示例值：661e****543cf
应用的唯一标志。
RoomId String 必选示例值：Room1
通话房间 ID。
需与调用 StartVoiceChat 启动任务时使用的 RoomId 保持一致。
TaskId String 必选示例值：Task1
目标智能体任务的 ID。
需与调用 StartVoiceChat 启动任务时定义的 TaskId 保持一致。
Command String 必选示例值：interrupt
要执行的指令，决定本次请求的操作意图：
- interrupt：打断智能体说话。使用方法参见手动打断。
- function：用于 Function Calling 场景，回传工具执行结果。使用方法，可参见 函数调用 Function Calling。
- ExternalTextToSpeech：将指定文本直接送入 TTS 让智能体主动播报（需配合 Message 和InterruptMode 字段）。使用方法参看自定义语音播放。
- ExternalPromptsForLLM：发送自定义文本作为背景信息，与用户的下一轮语音输入拼接后一同送入 LLM（需配合 Message 字段）。使用方法，可参见动态传入上下文。注意：此指令在启用端到端语音模型（S2SConfig）时无效。
- ExternalTextToLLM：向 LLM 发送文本或图片信息，直接触发 LLM 回复。注意：此指令在启用端到端语音模型（S2SConfig）时无效。
- 文本提问：配合使用 Message 字段，作为当前轮次的用户文本输入。使用方法，可参见通过文本直接提问。
- 图片理解：传入 ImageConfig 字段发送图片，可同时配合 Message 字段（选填）传入关于图片的文本问题。使用方法，可参见图片理解（发送外部图片问答）。
- FinishSpeechRecognition：强制结束当前对话，触发新一轮对话。使用方法，可参见判停与对话触发。
- UpdateParameters：更新智能体配置，需配合 Parameters 字段使用。
- SetTTSContext：为下一轮对话动态设置 TTS 指令标签，使播报具备情感。需配合 Message 字段使用。具体使用方法，请参见情绪识别与生成。注意：该指令仅在使用豆包语音的语音合成大模型（流式输入流式输出），且在 StartVoiceChat 配置 Context.TagParse 为 ture 时生效。
- UpdateVoicePrintSV：声纹降噪配置，包括关闭或关闭声纹降噪功能、从预注册声纹切换至实时声纹、更新实时声纹注册时长。注意：该指令仅在 StartVoiceChat 中 VoicePrint.Mode 为 1 时生效。详细功能说明，请参见动态开启、关闭或更新声纹降噪。
- UpdateFarfieldConfig：更新远场人声抑制配置。注意：该指令仅在使用豆包语音的语音识别大模型或声音复刻大模型时生效。
- AudioCtrl：控制当前轮次 TTS 播报音频的播放状态，如暂停或继续播放。需配合 AudioConfig 字段使用。
Message String 可选 示例值："{"ToolCallID":"call_cx","Content":"上海天气是台风"}"
指令内容。该字段是否必填及内容格式，取决于 Command 的取值：
- Command 为 function：必填。填入工具执行结果（JSON 字符串）。示例："{\"ToolCallID\":\"call_cx**\",\"Content\":\"上海今天台风\"}"。
- Command 为 ExternalTextToSpeech：必填。填入需智能体播报的普通文本。建议长度不超过 200 个字符，以避免合成延迟过高影响体验。
- Command 为 ExternalPromptsForLLM：必填。填入需注入 LLM 的背景提示词文本。
- Command 为 ExternalTextToLLM：
- 纯文本提问：必填。填入文本问题，且末尾必须包含标点符号。
- 图片理解：分场景。
- 若传入 Message：作为图片关联的文本问题（如“这张图里有什么？”），系统会将图片 + 文本送入 LLM，并触发 LLM 生成回复。
- 若传入 Message：系统仅将图片缓存到当前轮次（GroupID）的上下文中，不触发 LLM 回复，等待后续指令。适用于分片上传或多图上传场景。
- 当 Command 为 SetTTSContext 时：必填。填入要设置的 TTS 标签（必须为 JSON 转义字符串），该标签仅对下一轮回答生效。Message 格式取决于您在 StartVoiceChat 中通过 ResourceId 指定的 TTS 模型版本：
- 语音合成大模型 2.0："{\"Tag\":{\"additions\":{\"context_texts\":[\"你的语气再欢乐一点\"]}}}"
- 语音合成大模型 1.0："{\"Tag\":{\"audio_params\":{\"emotion\":\"happy\",\"emotion_scale\":5}}}"
- 详细说明，请参见情绪识别与生成。
- 当 Command 为 UpdateVoicePrintSV 时：必填。一个 JSON 转义字符串，示例："{\"Enable\": true, \"VoiceDuration\": 10}"。
- Enable (Boolean)：开启或关闭声纹降噪。
- VoiceDuration：自动注册声纹所需的有效说话时长。取值为 [2, 33]，单位为秒。
- 当 Command 为 UpdateFarfieldConfig 时，必填。一个 JSON 转义字符串，示例："{\"Enable\": true, \"Level\": \"Medium\", \"Threshold\": 0, \"FixedSource\": false}"。参数说明及取值要求，参见 StartVoiceChat 中的 FarfieldConfig。
- 其他 Command：此字段可忽略，无需填写。
InterruptMode Integer 可选 示例值：1
指令处理优先级。用于控制当智能体当前正在进行交互（如正在说话或思考）时，如何处理本次请求传入的内容。
注意
仅当 command 为 ExternalTextToSpeech 或 ExternalTextToLLM时生效且必填。
取值说明：
- 1：高优先级。强制终止智能体当前的动作（说话或思考），立即执行本次指令。
- 2：中优先级。不打断当前交互，等待智能体完成当前回应后，再执行本次指令。
- 3：低优先级。如果智能体处于交互状态，则直接丢弃本次传入的文本或图片信息；如果智能体未在交互，则执行本次指令。
ImageConfig Object 可选 示例值：-
图片配置。用于向具备视觉能力的 LLM 传入图片数据（URL），实现图片问答。
注意
仅当 Command 为 ExternalTextToLLM时生效。
Action String 必选示例值：insert
对图片的操作类型，取值如下：
- insert：传入图片。将图片发送给 LLM 进行理解。系统会暂时缓存这些图片，以便与后续的文本问题关联。还需填 Images（URL列表）和 GroupID。
- delete：删除指定 GroupID 下已缓存的图片数据。
GroupID Integer 必选示例值：2
图片轮次 ID。Action 取值不同作用不同：
- Action 为 insert 时：用于将图片或后续的文本问题关联到同一轮对话中。该 ID 由您自定义和维护，需保证 ID 单调递增。
- Action 为 delete 时：使用 GroupID 来指定要清除哪一轮的图片缓存。
ImageType String 可选 示例值：url
图片数据格式。目前固定为 url。
注意
仅当 Action 为 insert时生效且必填。
Images String[] 可选 示例值：["https://your-tos-bucket.volces.com/path/to/image.jpg"]
指定要传入的图片 URL 地址，必须确保 URL 可被公网访问，否则大模型无法下载解析。
注意
仅当 Action 为 insert时生效且必填。
Parameters Object 可选 示例值：-
智能体配置参数。
注意
仅当 Command 为 UpdateParameters时生效且必填。
Config Object 可选 示例值：-
包含 LLM、TTS 等模块的具体配置。
LLMConfig Object 可选 示例值：-
大模型相关配置。
SystemMessages String[] 可选 示例值：["你是小宁，性格幽默又善解人意。你在表达时需简明扼要，有自己的观点。"]
系统提示词。用于定义智能体的角色设定、行为准则、回复语气及输出格式等。
- 更新：传入新的字符串数组，将覆盖旧配置。
- 清除：传入空数组 [] 或 null，可清除当前预设的系统提示词。
UserPrompts Object[] 可选 示例值：-
用户提示词。即预设的用户输入与回答，用于引导模型生成特定的输出或设定对话背景。
- 更新：传入包含 Role 和 Content 的对象数组，将全量覆盖旧配置。
- 清除：传入空数组 [] 或 null，可清除当前预设的用户提示词。
注意
UserPrompts 设有自动逐出机制：当上下文轮数超过 HistoryLength 限制时，最早的 UserPrompts 会被自动逐出，为新的对话历史腾出空间。一组 user 和 assistant 计为一轮。
示例：若 HistoryLength 设置为 3 且已预存 了 2 轮 UserPrompts。在用户与 AI 完成第 1 轮真实对话后，上下文总轮数为 3，此时无需逐出；当用户发起第 2 轮对话时，总轮数变为 4 超过限制，系统会自动移除最早的一轮 UserPrompts，使上下文始终只保留最近的 3 轮记录。
Role String 可选 示例值：user
发送消息的角色。支持取值 system、user 和 assistant。其中 user 和 assistant 必须成对出现（一问一答），否则大模型可能会出现未定义行为。
Content String 可选 示例值：你是谁？
消息内容。
TopUserPrompts Object[] 可选 示例值：-
必须始终保留的用户提示词，用于向大模型注入需持续参考的上下文；支持设置文本与图片。
注意
- TopUserPrompts 会占用 HistoryLength（历史对话轮数）。一组 user 和 assistant 计为一轮。例如 HistoryLength 为 10，配置 1 组 TopUserPrompts（一个 user 和一个 assistant）后，剩余可保留的普通历史对话为 9 轮。请根据实际需求合理控制注入的 TopUserPrompts。
- 仅火山方舟模型支持该功能。
Role String 必选示例值：user
消息角色。支持取值：user、assistant。
user 和 assistant 必须成对出现（一问一答），否则大模型可能会出现未定义行为。
Content String 必选示例值：第一张照片是李雷，喜欢踢足球；第二张照片是韩梅梅，喜欢学英语，爱吃雪糕。
文本上下文。用自然语言描述需要模型持续记住的信息。
注意
当该条消息同时携带 MultiModalContent 时，Content需与图片一一对应说明，避免图片与文案错配。
MultiModalContent Object[] 可选 示例值：-
多模态内容，用于添加图片信息。
注意
- 仅当 role 为 user 时生效，role=assistant 时不允许携带 MultiModalContent。
- 需确保 LLM 模型支持视觉理解能力，且已开启视觉理解（即 VisionConfig.Enable 为 true）。
- 此功能是基于 LLM 多模态能力的语义识别，而非传统的生物特征比对，不建议用于支付验证等高安全性场景。
示例：
"MultiModalContent": [{
"Type": "image",
"ImageUrl": "https://example.com/image1.jpg "
}, {
"Type": "image",
"ImageUrl": "https://example.com/image2.jpg "
}]
Type String 必选示例值：image
多模态数据类型。当前仅支持取值 `image`。
ImageUrl String 必选示例值：https://example.com/image.jpg
图片 URL。需确保该 URL 可以在公网环境下直接访问。
注意
Tools Object[] 可选 示例值：-
更新 Function Calling 工具列表，或关闭 Function Calling 功能。
- 更新工具：传入包含新工具定义的数组，覆盖旧配置。
- 关闭 Function Calling 功能：设为 null 或 []，即可。例如 {"Tools": null}。
type String 可选 示例值：function
工具类型。目前固定取值 function，表示函数调用。
function Object 可选 示例值：-
指定模型可以调用的函数列表。
name String 可选 示例值：get_current_weather
函数的名称。
建议使用清晰、能体现函数作用的英文名。如 get_current_weather，而不是 tool_1 或 my_func。
description String 可选 示例值：获取指定城市的天气信息
函数用途的描述。
大模型会参考该字段来选择是否使用该函数。建议用一句话清晰概述参数的用途、格式要求，并提供示例。
parameters JSONMap 可选 示例值：-
函数的请求参数。大模型会参考该字段来提取函数的入参；如果函数不需要输入参数，则无需指定 parameters 参数。
- type：必须是 "object"。
- properties：列出支持的所有参数名及其类型。
- 参数名：须为英文字符串，且不能重复。
- type：需遵循 JSON 规范，支持类型包括 string、number、boolean、integer、object、array。
- description：对参数的清晰描述。引导模型正确提取值，建议包含用途和格式示例。
- required：指定函数中必填的参数名，未在此列出的参数则被视为可选。
示例：
{
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "需要查询天气的城市名，例如：'北京市'"
},
"date": {
"type": "string",
"description": "查询的日期，格式应为 YYYY-MM-DD。如果省略，则表示查询当天天气。"
}
},
"required": ["location"]
}
VisionConfig Object 可选 示例值：-
视觉理解能力配置。可更新视觉理解配置，或关闭视觉理解。
- 更新/开启：配置 Enable 和 SnapshotConfig。如何使用视觉理解能力？
- 关闭：将 VisionConfig 设置为 null，或将 VisionConfig.Enable 设置为 false。
Enable Boolean 可选 示例值：true
是否开启视觉理解功能。
- false：不开启。
- true：开启。
默认值为 false。
SnapshotConfig Object 可选 示例值：-
抽帧截图配置。智能体会按照配置策略在后台自动抽帧截图送入大模型以供理解。
StreamType Integer 可选 示例值：0
截图流类型。
- 0：主流。指来自摄像头的实时视频画面。
- 1：屏幕共享流。指用户共享的设备屏幕内容（如桌面、应用窗口、PPT 等）。
默认值为 0。
TTSConfig Object 可选 示例值：-
语音合成（TTS）相关配置。你可以按需进行以下操作：
- 修改当前 TTS 服务配置：若保持当前 TTS 服务不变，仅需传入要修改的字段（如只传 speed_ratio）。
- 切换 TTS 服务：如从豆包语音的“语音合成”切到“声音复刻”，必须同时将 Provider 和 ProviderParams 更换为新服务对应值和支持的字段，以确保覆盖旧配置。
Provider String 可选 示例值：volcano
语音合成服务提供商。
使用不同语音合成服务时，取值不同。支持使用的语音合成服务及对应取值如下：
- volcano_bidirection（服务自上而下语音生成速度递减，情感表现力递增）
- （豆包语音）语音合成大模型（流式输入流式输出）
- （豆包语音）声音复刻大模型（流式输入流式输出）
- minimax：MiniMax 语音合成
- ai_gateway：自定义语音合成模型（通过火山边缘大模型网关接入的）
ProviderParams 可选 示例值：-
配置所选的语音合成服务。不同服务下，需配置的字段不同：
- （豆包语音）语音合成大模型（流式输入流式输出）
- （豆包语音）声音复刻大模型（流式输入流式输出）
（豆包语音）语音合成大模型（流式输入流式输出_参数透传） Object
此方式支持语音合成大模型（流式输入流式输出）所有配置参数，相较于直传配置更灵活、功能更全面。透传模型参数时，TTSConfig.ProviderParams 里包含以下字段：
Credential Object 可选 示例值：-
语音合成大模型服务的鉴权参数。
ResourceId String 可选 示例值：volc.service_type.10029
指定要使用的语音合成大模型的版本：
- seed-tts-1.0 或 volc.service_type.10029（默认值）：语音合成大模型 1.0 字符版
- seed-tts-2.0：语音合成大模型 2.0 字符版
VolcanoTTSParameters String 可选 示例值：{"req_params":{"speaker":"zh_female_linjianvhai_moon_bigtts"}}
- 必填参数：必须包含参数 req_params.speaker（音色）。
- 说明
音色需与在 Credential.ResourceId 指定的模型版本匹配 ，即使用语音合成大模型 1.0 服务仅支持 1.0 支持的音色；使用语音合成大模型 2.0 服务只能使用 2.0 支持的音色。详情可参见音色列表。
- 不可传入的参数：不可以包含以下由平台管理的参数：
- user
- event
- namespace
- req_params.text
- req_params.audio_params.format
- req_params.audio_params.enable_timestamp
- req_params.additions.max_length_to_filter_parenthesis
- req_params.additions.cache_config、req_params.additions.enable_latex_tn：仅当使用语音合成大模型 2.0（ResourceId 为 seed-tts-2.0）时，若启用了对齐时间戳的字幕（SubtitleMode: 0），不可传入。
- 其他参数：按需选择（例如 req_params.audio_params.speech_rate）。
示例：以设置指定的音色（必填）并调整语速（可选）为例
- 先构建如下 JSON：
- {"req_params": {"speaker": "zh_female_linjianvhai_moon_bigtts","audio_params": {"speech_rate": 100}}}
- 然后将其转换为 JSON 字符串：
"{\"req_params\":{\"speaker\":\"zh_female_linjianvhai_moon_bigtts\",\"audio_params\":{\"speech_rate\":100}}}"
（豆包语音）语音合成大模型（流式输入流式输出_参数直传） Object
此方式封装了语音合成大模型（流式输入流式输出）部分通用参数，接入简单，但无法使用该服务的全部功能。直传模型参数时， TTSConfig.ProviderParams 包含以下字段：
audio Object 可选 示例值：-
语音合成大模型服务音频配置。
voice_type String 可选 示例值：BV001_streaming
音色。填入音色对应的标识 voice_type，需与在 ResourceId 中指定的模型版本匹配：
- 使用语音合成大模型 1.0 服务仅支持 1.0 支持的音色。
- 使用语音合成大模型 2.0 服务仅支持 2.0 支持的音色。
speech_rate Integer 可选 示例值：0
语速。取值范围 [-50, 100]，取值越大，语速越快。
- 100：2.0 倍速。
- -50：0.5 倍速。
- 0（默认值）：原语速。
ResourceId String 可选 示例值：volc.service_type.10029
指定要使用的语音合成大模型的版本：
- seed-tts-1.0 或 volc.service_type.10029（默认值）：语音合成大模型 1.0 字符版
- seed-tts-2.0：语音合成大模型 2.0 字符版
additions Object 可选 示例值：-
豆包语音的语音合成大模型服务高级配置。
enable_latex_tn Boolean 可选 示例值：true
播报 LaTeX 公式。启用后，AI 能够以自然语言朗读文本中的 LaTeX 格式的数学公式。
- false（默认值）：不播报。
- true：播报。 为 true 时，disable_markdown_filter 也需为 true 才生效。
效果示例：
- LLM 返回：根据公式 a^2 + b^2 = c^2 可知...
- AI 播报：根据公式 a 的平方加上 b 的平方等于 c 的平方 可知...
- 字幕显示：根据公式 a^2 + b^2 = c^2 可知...
注意
使用语音合成大模型 2.0 时，该功能与对齐时间戳的字幕功能（SubtitleMode: 0）不可同时开启。
disable_markdown_filter Boolean 可选 示例值：true
过滤 Markdown 格式。
启用后，语音合成时会自动过滤 LLM 返回文本中的 Markdown 格式符号（如加粗、标题等），确保语音播报的连贯性。
- false（默认值）：不过滤。
- true：过滤。
效果示例：
- LLM 返回：请执行 **grep** 命令查看日志。
- AI 播报：请执行 grep 命令查看日志。
- 字幕显示：请执行 **grep** 命令查看日志。
（豆包语音）声音复刻大模型（流式输入流式输出_参数透传） Object
此方式支持声音复刻大模型（流式输入流式输出）所有配置参数，相较于直传配置更灵活、功能更全面。透传模型参数时，TTSConfig.ProviderParams 包含以下字段：
Credential Object 必选示例值：-
声音复刻大模型的鉴权参数。
ResourceId String 必选示例值：seed-icl-2.0
指定要使用的声音复刻大模型服务版本。需与你在 VolcanoTTSParameters 传入的音色版本一致：
- seed-icl-1.0 ：声音复刻 1.0 字符版
- seed-icl-2.0：声音复刻 2.0 字符版
VolcanoTTSParameters String 可选 示例值："{"req_params":{"speaker":"S_The****K1"}}"
- 必填参数：必须包含参数 req_params.speaker ，即经过训练后的复刻声音 ID。根据使用的模型来源不同，获取方式不同。具体请参见复刻声音。
- 不可传入的参数：不可以包含以下由平台管理的参数：
- user
- event
- namespace
- req_params.text
- req_params.audio_params.format
- req_params.audio_params.enable_timestamp
- req_params.additions.max_length_to_filter_parenthesis
- req_params.additions.cache_config、req_params.additions.enable_latex_tn：仅当使用声音复刻大模型 2.0（ResourceId 为 seed-icl-2.0）时，若启用了对齐时间戳的字幕（SubtitleMode: 0），不可传入。
- 其他参数：按需选择（例如 req_params.audio_params.speech_rate）。
示例：以设置指定的音色（必填）并调整语速（可选）为例
- 先构建 JSON 对象：
{
"req_params": {
"speaker": "S_The****K1",
"audio_params": {
"speech_rate": 100
}
}
}
- 将其转换为 JSON 字符串：
"{\"req_params\":{\"speaker\":\"S_The****K1\",\"audio_params\":{\"speech_rate\":100}}}"
（豆包语音）声音复刻大模型（流式输入流式输出_参数直传） Object
此方式封装了声音复刻大模型（流式输入流式输出）部分通用参数，接入简单，但无法使用该 服务的全部功能。直传模型参数时，TTSConfig.ProviderParams 包含以下字段：
audio Object 可选 示例值：-
声音复刻大模型服务音频配置。
voice_type String 可选 示例值：S_N****T7k1
speech_rate Integer 可选 示例值：0
语速。取值范围 [-50, 100]，取值越大，语速越快。
- 100：2.0 倍速。
- -50：0.5 倍速。
- 0（默认值）：原语速。
ResourceId String 可选 示例值：seed-icl-2.0
指定要使用的声音复刻大模型服务版本。需要与您在 voice_type 中指定的音色版本一致：
- seed-icl-1.0 ：声音复刻 1.0 字符版
- seed-icl-2.0：声音复刻 2.0 字符版
additions Object 可选 示例值：-
声音复刻大模型服务高级配置。
enable_latex_tn Boolean 可选 示例值：true
播报 LaTeX 公式。启用后，AI 能够以自然语言朗读文本中的 LaTeX 格式的数学公式。
- false（默认值）：不播报。
- true：播报。 为 true 时，disable_markdown_filter 也需为 true 才生效。
效果示例：
- LLM 返回：根据公式 a^2 + b^2 = c^2 可知...
- AI 播报：根据公式 a 的平方加上 b 的平方等于 c 的平方 可知...
- 字幕显示：根据公式 a^2 + b^2 = c^2 可知...
注意
使用声音复刻大模型 2.0 时，该功能与对齐时间戳的字幕功能（SubtitleMode: 0）不可同时开启。
disable_markdown_filter Boolean 可选 示例值：true
过滤 Markdown 格式。
启用后，语音合成时会自动过滤 LLM 返回文本中的 Markdown 格式符号（如加粗、标题等），确保语音播报的连贯性。
- false（默认值）：不过滤。
- true：过滤。
效果示例：
- LLM 返回：请执行 **grep** 命令查看日志。
- AI 播报：请执行 grep 命令查看日志。
- 字幕显示：请执行 **grep** 命令查看日志。
MiniMax 语音合成 Object
使用 MiniMax 语音合成时， TTSConfig.ProviderParams 包含以下字段：
Authorization String 可选 示例值：eyJhbG****SUzI1N
Groupid String 可选 示例值：983*****669
model String 可选 示例值：speech-01-turbo
发起请求的模型版本：
- speech-01-turbo：最新模型，拥有出色的效果与时延表现。
- speech-01-240228：稳定版本模型，效果出色。
- speech-01-turbo-240228：稳定版本模型，时延更低。
URL String 可选 示例值：https://api.minimax.chat/v1/t2a_v2
请求语音合成 URL，该参数固定取值：https://api.minimax.chat/v1/t2a_v2。
voice_setting Object 可选 示例值：-
音频配置。
speed Float 可选 示例值：1.0
语速。取值越大，语速越快。
取值范围为 [0.5, 2]，默认值为 1.0。
vol Float 可选 示例值：1.0
音量。取值越大，音量越高。
取值范围为 (0, 10]，默认值为 1.0。
pitch Float 可选 示例值：0.0
语调。取值越大，语调越高。
取值范围为 [-12, 12]，且必须为整数。
默认值为 0，表示原音色输出。
voice_id String 可选 示例值：male-qn-jingying
系统音色编号/复刻音色编号。
- 系统音色可前往 voice_setting.voice_id 查询。
- 克隆音色参看 FAQ。
注意
voice_id 与 timber_weights必须设置其中一个。
pronunciation_dict Object 可选 示例值：-
特殊标注配置。可对特殊文字、符号指定发音。
tone String[] 可选 示例值：["燕少飞/(yan4)(shao3)(fei1)","达菲/(da2)(fei1)"，"omg/oh my god"]
用于替换需要特殊标注的文字、符号及对应的发音，可用于调整声调或指定其他字符的发音。格式为 "原文字/注音"，注音部分根据语言类型采用不同方式标注：
- 英文注音：使用对应发音的英文单词，例如："omg/oh my god"。
- 中文注音：使用拼音，并在每个音节后以括号标注声调，音调用数字表示：
- 一声（阴平）：1
- 二声（阳平）：2
- 三声（上声）：3
- 四声（去声）：4
- 轻声：5
- 例如，"燕少飞/(yan4)(shao3)(fei1)"、"达菲/(da2)(fei1)"。
默认为空。
timber_weights Object[] 可选 示例值：-
合成音色权重设置。可通过该参数设置多种音色混合，并调整每个具体音色权重。最多支持 4 种音色混合。
注意
timber_weights 与 VoiceSetting.voice_id必须设置其中一个。
voice_id String 可选 示例值：male-qn-jingying
weight Integer 可选 示例值：1
权重。取值为整数，单一音色取值占比越高，合成音色越像。取值范围为 [1, 100]。
stream Boolean 可选 示例值：false
是否开启流式输出。
- false：不开启流式输出。
- true：开启流式输出。
默认值为 false。
自定义语音合成 Object
使用自定义语音合成时，TTSConfig.ProviderParams 包含以下字段：
URL String 可选 示例值：wss://ai-gateway.vei.volces.com/v1/realtime?model=ttsname
边缘大模型网关的服务接入点 URL。StartVoiceChat 会通过此地址连接到网关，网关再将请求转发给你的定义 TTS 服务。
URL 为固定格式：wss://ai-gateway.vei.volces.com/v1/realtime?model=<TTS 调用名称>
Voice String 可选 示例值：-
音色。填入自定义 TTS 服务所支持的音色名称。
OutputAudioSpeedRate Float 可选 示例值：0.0
语速。
透传字段，限制或实际行为与自定义模型保持一致。
OutputAudioVolume Float 可选 示例值：1.0
音量。
透传字段，限制或实际行为与自定义模型保持一致。
OutputAudioPitchRate Float 可选 示例值：0.0
音调。
透传字段，限制或实际行为与自定义模型保持一致。
ExtraData JSONMap 可选 示例值：-
传入自定义参数，将以 JSON 格式透传给你的自定义 TTS 服务。
ExtraHeader JSONMap 可选 示例值：-
自定义透传 Header。一个 JSON 对象，其键值对将作为额外的 HTTP Header 字段，透传到您的自定义 TTS 服务请求中，可用于鉴权或其他自定义逻辑。
language_boost String 可选 示例值：auto
增强指定小语种/方言场景下的语音表现。不同场景下取值及含义如下：
- 不明确小语种类型：auto。取值为 auto 时，模型将自主判断小语种类型。
- 小语种：
- Spanish：西班牙语
- French：法语
- Portuguese：葡萄牙语
- Korean：韩语
- Indonesian：印度尼西亚语
- German：德语
- Japanese：日语
- Italian：意大利语
- auto：自动模式
- 方言：
- Chinese,Yue：粤语。Chinese,Yue 仅当 MiniMaxTTSConfig.model=speech-01-turbo 时生效。
默认值为空。
IgnoreBracketText Integer[] 可选 示例值：[1,2]
过滤 LLM 返回内容中指定括号内的文字，再进行语音合成。
您可通过 System Prompt 引导 LLM 在回复文本中生成指定格式的自定义指令（如动作、情绪）。同时结合该字段让指令不被 TTS 播报，且会随字幕下发至客户端，用于实现本地业务逻辑，触发客户端 UI 等场景。
支持取值（默认为空，表示不过滤）：
- 1：中文括号 （）
- 2：英文括号 ()
- 3：中文方括号 【】
- 4：英文方括号 []
- 5：英文花括号 {}
使用说明
- 使用限制：该功能仅在使用豆包语音的 TTS 服务时生效。
- 使用方法：参见传递自定义指令。
- 长度限制：单组括号内的内容长度上限为 500 字符，超出限制的内容将无法被过滤。
- 字幕显示：一般情况下，被过滤的内容仍会显示在字幕中，但不会被播放。若括号内容位于回复的最末端，且被判定为独立句子（其后无其他有效语义），则会显示在字幕中。
- ...我知无不言！(自信满满）。 → (自信满满）。不会显示在字幕中。
- ...我知无不言（自信满满）！ → (自信满满）！ 会显示在字幕中。
InterruptMode Integer 可选 示例值：0
是否启用语音打断（发声即打断）：
- 0：开启。开启后，一旦检测到用户发出声音，智能体立刻停止输出。
- 1：关闭。关闭后，智能体说话期间，用户语音输入内容会被忽略不做处理，不会打断智能体讲话。
默认值为 0。
AudioConfig Object 可选 示例值：-
音频控制参数。
注意
仅当 Command 为 AudioCtrl时生效且必填。
Action String 必选示例值：pause
音频播放操作：
- pause：暂停播放。
- play：继续播放。
注意
- 仅对当前轮次的对话生效。若智能体被打断或开启新一轮对话，则控制状态自动失效。
- 开启音频快速发送（AgentConfig.Burst）功能后，暂停或恢复 AI 音频播放功能将失效。
AdvanceConfig Object 可选 示例值：-
外部文本播报的高级配置。用于指定外部文本所属的对话轮次，并将业务自定义信息随该轮字幕透传给客户端。
典型场景：当需要将大量自定义文本作为 AI 回复播报时（例如外部大模型的流式回复、长篇的业务话术等），若还需要知道这段播报属于哪条业务回复、当前回复是否结束、后续是否要继续等待等。此时可将业务协议写入 CustomInfo，由系统随字幕透传给客户端或服务端。
注意
仅当 Command 为 ExternalTextToSpeech时生效。
RoundID Integer 可选 示例值：3
本次外部文本播报所属的对话轮次 ID。
CustomInfo JSONMap 可选 示例值：{"finish": true}
业务自定义信息，需使用键值对。系统会将该自定义信息随同一轮次的字幕通过 customInfo 原样透传给客户端或服务端。
注意
- 建议仅传入业务关联所需的信息，避免传入敏感数据或过大的对象。
- 若本次外部文本进入安抚语处理逻辑，CustomInfo不会随字幕下发。
返回参数
其中返回值 Result 仅在请求成功时返回 ok，失败时为空。
错误码
手动打断 AI
回传 Function Calling 结果
传入自定义文本让 AI 播报
传入文本直接向 AI 提问
向智能体发送图片并提问
传入文本作为下一轮回答的参考
手动触发下一轮对话
更新 Function Calling 配置（以更新工具列表为例）
传入情绪指令标签（TTS 2.0）
更新远场人声抑制配置
更新实时声纹注册配置
输入示例
POST https://rtc.volcengineapi.com?Action=UpdateVoiceChat&Version=2025-06-01
{
"AppId": "661e****543cf",
"RoomId": "Room1",
"TaskId": "task1",
"Command": "interrupt"
}输出示例
{
"ResponseMetadata": {
"RequestId": "20250604110420****100232280022D31",
"Action": "UpdateVoiceChat",
"Version": "2025-06-01",
"Service": "rtc",
"Region": "cn-north-1"
}
}最近更新时间：2026.10.08 11:06:50
这个页面对您有帮助吗？
有用
有用
无用
无用