在实时音视频场景中,若你希望启动智能体提供语音聊天服务,可以通过调用此接口实现。
你可以根据需要设定应用标识、房间 ID、订阅用户 ID 以及 ASR、TTS 和 LLM 相关高级配置,个性化定制智能体的行为和交互方式。
请求频率:单账号下 QPS 不得超过 60。
使用智能体进行对话前,你需要开通 ASR、 TTS 和大模型服务并配置相关策略,详情请参看开通服务。
关于调用接口的请求结构、公共参数、签名方法、返回结构,参看调用方法。
下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
Action | String | 是 | StartVoiceChat | 接口名称。当前 API 的名称为 StartVoiceChat 。 |
Version | String | 是 | 2024-06-01 | 接口版本。当前 API 的版本为 2024-06-01 。 |
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
AppId | String | 是 | 661e****543cf | 你的音视频应用的唯一标志,参看获取 AppId。 |
RoomId | String | 是 | Room1 | 房间的 ID,是房间的唯一标志。赋值规则参看参数赋值规范。 |
UserId | String | 是 | User1 | 客户端用户的 UserId。 |
Config | Object of Config | 是 | - | ASR、TTS 和 LLM 相关高级配置。 |
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
BotName | String | 否 |
| 房间内智能体名称。赋值规则参看参数赋值规范。 注意 BotName 与 UserId 取值不能重复。 |
ASRConfig | Object of ASRConfig | 是 | - | 流式语音识别相关配置。 |
TTSConfig | Object of TTSConfig | 是 | - | 语音合成相关配置。 |
LLMConfig | Object of LLMConfig | 是 |
| 大模型相关配置,不同的大模型该参数结构不同: |
SubtitleConfig | Object of SubtitleConfig | 否 | - | 房间内字幕相关配置。 |
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
AppId | String | 是 | 93****21 | 已开通流式语音服务 的 AppId。 |
Cluster | String | 否 | volcengine_streaming_common | 具体流式语音识别服务对应的 Cluster ID,可在流式语音服务控制台开通对应服务后查询。 默认为办公-中文的 Cluster ID: volcengine_streaming_common 。 |
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
AppId | String | 是 | 94****11 | 已开通需要的语音合成服务的 AppId。 |
Cluster | String | 否 | volcano_tts | 具体语音合成服务对应的 Cluster ID。
volcano_tts 。 |
VoiceType | String | 否 | BV002_streaming | 具体语音合成服务开通音色 ID。
Voice_typeBV002_streaming 。 |
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
Mode | String | 是 |
| 大模型名称,该参数固定取值: |
EndPointId | String | 否 |
| 推理接入点。使用方舟模型时必填。 注意 EndPointId 与 BotId 任选其一。若同时填写,则 EndPointId 生效。 |
BotId | String | 否 |
| 智能体 ID。使用方舟智能体时为必填。 |
MaxTokens | Integer | 否 | 1024 | 输出文本的最大 token 限制。默认值为 1024 。 |
Temperature | Integer | 否 | 0.1 | 采样温度,用于控制生成文本的随机性和创造性,值越大随机性越高。取值范围为(0,1] ,默认值为 0.1 。 |
TopP | Float | 否 | 0.3 | 采样的选择范围,控制输出 token 的多样性。模型将从概率分布中累计概率超过该取值的标记中进行采样,以确保采样的选择范围不会过宽,值越大输出的 token 类型越丰富。 取值范围为[0,1] ,默认值为 0.3 。 |
SystemMessages | Array of String | 否 |
| 大模型 System 角色预设指令,可用于控制模型输出。 |
UserMessages | Array of String | 否 | ["user:\"你是谁\"", "assistant:\"我是问答助手\"","user:\"你能干什么\"","user:\"我能回答问题\""] | 大模型 User 角色预设 Prompt,可用于增强模型的回复质量,模型回复时会优先参考此处内容。 |
HistoryLength | Integer | 否 |
| 历史问题轮数。默认值为 |
WelcomeSpeech | String | 否 | Hello | 智能体启动后的欢迎词。 |
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
Mode | String | 是 |
| 大模型名称。使用第三方大模型时,该参数固定取值: |
URL | String | 是 |
| 第三方大模型 URL,需要使用 HTTPS 域名。 注意 如需使用 http 域名进行测试,Feature 参数的值必须为 |
ModelName | String | 否 | moonshot | 第三方大模型名称。 |
APIKey | String | 否 | pat*****123231 | Bearer Token 认证方式的大模型 token。 |
MaxTokens | Integer | 否 | 1024 | 输出文本的最大 token 限制。默认值为 1024 。 |
Temperature | Integer | 否 | 0.1 | 采样温度,用于控制生成文本的随机性和创造性,值越大随机性越高。取值范围为(0,1] ,默认值为 0.1 。 |
TopP | Float | 否 | 0.3 | 采样的选择范围,控制输出 token 的多样性。模型将从概率分布中累计概率超过该取值的标记中进行采样,以确保采样的选择范围不会过宽,值越大输出的 token 类型越丰富。 取值范围为[0,1] ,默认值为 0.3 。 |
SystemMessages | Array of String | 否 |
| 大模型 System 角色预设指令,可用于控制模型输出。 |
UserMessages | Array of String | 否 | ["user:\"你是谁\"", "assistant:\"我是问答助手\"","user:\"你能干什么\"","user:\"我能回答问题\""] | 大模型 User 角色预设 Prompt,可用于增强模型的回复质量,模型回复时会优先参考此处内容。 |
HistoryLength | Integer | 否 | 3 | 历史问题轮数。默认值为 3 。 在调用该接口时需要确保所有 UserMessage 和 SystemMessage 消息文本总长度小于大模型上下文长度。 例如:历史问题轮数为 3,使用 Skylark2-lite-8k 大模型,预设 SystemMessage 和 UserMessage 各两条,询问第 10 个问题时,需保证预设的两条 SystemMessage 、预设的两条 UserMessage 与第八、九、十条问题的总长度之和不得超过 8k。 |
WelcomeSpeech | String | 否 | Hello | 智能体启动后的欢迎词。 |
Feature | String | 否 | {\"Http\":true} | 该参数固定取值:{\"Http\":true} ,表示使用 HTTP 域名进行测试。 |
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
DisableRTSSubtitle | Boolean | 否 | false | 是否关闭房间内字幕回调。
false 。字幕功能详细说明参看实时字幕。 |
ServerMessageUrl | String | 否 | https://example-domain.com/vertc/subtitle | 接受字幕结果的 URL 地址。 接收结果的 URL 必须以域名开头。如果 URL 为 HTTPS 域名,请确保该域名 SSL 证书合法且完整。 ServerMessageUrl 和 ServerMessageSignature 均填写正确才能开启服务端字幕功能。 |
ServerMessageSignature | String | 否 | b46ab5f1d8ad6a | 鉴权签名。 你可传入该鉴权参数,在接收到字幕结果后,与结果中的 signature 字段值进行对比以进行鉴权验证。 |
本接口无特有的返回参数。公共返回参数请见返回结构。
其中返回值 Result
仅在请求成功时返回 ok
,失败时为空。
POST https://rtc.volcengineapi.com?Action=StartVoiceChat&Version=2024-06-01 { "AppId": "661e****543cf", "RoomId": "Room1", "UserId": "User1", "Config": { "BotName": "audiobot_user1_1611736812853", "ASRConfig": { "AppId": "93****21", "Cluster": "volcengine_streaming_common" }, "TTSConfig": { "AppId": "94****11", "Cluster": "volcano_tts", "VoiceType": "BV002_streaming" }, "LLMConfig": { "Mode": "ArkV3", "EndPointId": "epid****212", "MaxTokens": 1024, "Temperature": 0, "TopP": 0.3, "SystemMessages": [ "你是小宁,性格幽默又善解人意。你在表达时需简明扼要,有自己的观点。" ], "UserMessages": [ "user:\"你是谁\"", "assistant:\"我是问答助手\"", "user:\"你能干什么\"", "user:\"我能回答问题\"" ], "HistoryLength": 3, "WelcomeSpeech": "Hello" } } }
POST https://rtc.volcengineapi.com?Action=StartVoiceChat&Version=2024-06-01 { "AppId": "661e****543cf", "RoomId": "Room1", "UserId": "User1", "Config": { "BotName": "audiobot_user1_1611736812853", "ASRConfig": { "AppId": "93****21", "Cluster": "volcengine_streaming_common" }, "TTSConfig": { "AppId": "94****11", "Cluster": "volcano_tts", "VoiceType": "BV002_streaming" }, "LLMConfig": { "Mode": "CustomLLM", "URL": "https:test.com", "MaxTokens": 1024, "Temperature": 0, "TopP": 0.3, "SystemMessages": [ "你是小宁,性格幽默又善解人意。你在表达时需简明扼要,有自己的观点。" ], "UserMessages": [ "user:\"你是谁\"", "assistant:\"我是问答助手\"", "user:\"你能干什么\"", "user:\"我能回答问题\"" ], "HistoryLength": 3, "WelcomeSpeech": "Hello" } } }
{ "Result": "ok", "ResponseMetadata": { "RequestId": "20230****10420", "Action": "StartVoiceChat", "Version": "2024-06-01", "Service": "rtc", "Region": "cn-north-1" } }