启动智能体 StartVoiceChat--实时音视频-火山引擎

文档中心

立即注册

导航

启动智能体 StartVoiceChat

最近更新时间：2024.12.18 15:18:02首次发布时间：2024.07.16 17:04:59

在实时音视频场景中，若你希望启动智能体提供语音聊天服务，可以通过调用此接口实现。

你可以根据需要设定应用标识、房间 ID、订阅用户 ID 以及 ASR、TTS 和 LLM 相关高级配置，个性化定制智能体的行为和交互方式。

注意事项

请求频率：单账号下 QPS 不得超过 60。
该接口请求接入地址仅支持 rtc.volcengineapi.com。
若启动智能体任务一段时间后，房间内用户均已退房，180 s 后智能体任务会自动停止，但该 180s 内仍会计费。

前提条件

使用智能体进行对话前，你需要开通 ASR、 TTS 和大模型服务并配置相关策略，详情请参看开通服务。

调用接口

关于调用接口的请求结构、公共参数、签名方法、返回结构，参看调用方法。

请求说明

请求方式：POST
请求地址：https://rtc.volcengineapi.com?Action=StartVoiceChat&Version=2024-06-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`StartVoiceChat`	接口名称。当前 API 的名称为 `StartVoiceChat`。
Version	String	是	`2024-06-01`	接口版本。当前 API 的版本为 `2024-06-01`。

Body

参数	类型	是否必选	示例值	描述
AppId	String	是	`661e****543cf`	你的音视频应用的唯一标志，参看获取 AppId。
RoomId	String	是	`Room1`	房间的 ID，是房间的唯一标志。赋值规则参看参数赋值规范。
UserId	String	是	`User1`	客户端用户的 UserId。
Config	Object of Config	是	`-`	ASR、TTS 和 LLM 相关高级配置。

Config

参数	类型	是否必选	示例值	描述
BotName	String	否	`voiceChat_user1_1611736812853`	房间内智能体名称。赋值规则参看参数赋值规范。若不填则默认值为`voiceChat_$(UserId)_$(timestamp_now)`。注意 BotName 与 UserId 取值不能重复。
ASRConfig	Object of ASRConfig	是	`-`	流式语音识别相关配置。
TTSConfig	Object of TTSConfig	是	`-`	语音合成相关配置。
LLMConfig	Object	是	`-`	大模型相关配置，不同的大模型该参数结构不同：方舟大模型：ARKLLMConfig。第三方大模型：ThirdPartyLLMConfig。
SubtitleConfig	Object of SubtitleConfig	否	`-`	房间内字幕相关配置。
InterruptMode	Integer	否	`0`	打断模式。支持取值及含义如下： `0`：语音自动打断； `1`：禁用语音打断。取该值时，智能体说话期间，用户的输入内容会被忽略不做处理。默认值为 `0`。

ASRConfig

参数	类型	是否必选	示例值	描述
AppId	String	是	`93****21`	已开通流式语音服务的 AppId。
Cluster	String	是	`volcengine_streaming_common`	具体流式语音识别服务对应的 Cluster ID，可在流式语音服务控制台开通对应服务后查询。默认为通用-中文的 Cluster ID： `volcengine_streaming_common`。
VADConfig	Object of VADConfig	否	`-`	VAD 配置。
VolumeGain	Float	否	`0.3`	音量增益值。降低采集音量，以减少噪音引起的 ASR 错误识别。默认值为 `1.0`，推荐值 `0.3`。

VADConfig

参数	类型	是否必选	示例值	描述
SilenceTime	Integer	否	`600`	判停时间。停顿时间若高于该值设定时间，则认为一句话结束。单位为 `ms`，默认值为 `600`。

TTSConfig

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
IgnoreBracketText	Array of Integer	否	`[1,2]`	过滤大模型返回内容中指定标点符号中的文字后再进行语音合成。你需要在大模型 Prompt 中自行定义哪些内容放在指定标点符号内。具体参看过滤指定内容。支持取值及含义如下： `1`：中文括号（） `2`：英文括号() `3`：中文方括号【】 `4`：英文方括号[] `5`：英文花括号{} 默认值为空，表示不进行过滤。
Provider	String	是	`-`	语音合成服务提供商，支持取值及含义如下： `volcano`：火山引擎语音技术。 `minimax`：MiniMax。
ProviderParams	Object	是	`-`	服务配置参数。不同服务下该参数结构不同：火山引擎语音技术：VolcanoTTSConfig； MiniMax：MiniMaxTTSConfig。

IgnoreBracketText

Array of Integer

否

[1,2]

过滤大模型返回内容中指定标点符号中的文字后再进行语音合成。你需要在大模型 Prompt 中自行定义哪些内容放在指定标点符号内。具体参看过滤指定内容。
支持取值及含义如下：

1：中文括号（）
2：英文括号()
3：中文方括号【】
4：英文方括号[]
5：英文花括号{}
默认值为空，表示不进行过滤。

Provider

String

是

-

语音合成服务提供商，支持取值及含义如下：

volcano：火山引擎语音技术。
minimax：MiniMax。

ProviderParams

Object

是

-

服务配置参数。不同服务下该参数结构不同：

火山引擎语音技术：VolcanoTTSConfig；
MiniMax：MiniMaxTTSConfig。

VolcanoTTSConfig

参数	类型	是否必选	示例值	描述
app	Object of App	否	`-`	火山语音技术应用配置。
audio	Object of Audio	否	`-`	火山语音技术音频配置。

App

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
appid	String	否	`94****11`	已开通需要的语音合成服务的 AppId。注意使用火山语音技术服务时，该参数为必填。
cluster	String	否	`volcano_tts`	具体语音合成服务对应的 Cluster ID。音频生成-语音合成服务：`volcano_tts`；大模型音频生成-大模型语音合成服务：`volcano_tts`；大模型音频生成-大模型声音复刻 2.0 服务（字符版）：`volcano_icl`。大模型音频生成-大模型声音复刻 2.0 服务（并发版）：`volcano_icl_concurr`。默认值为音频生成-语音合成服务对应的 Cluster ID: `volcano_tts`。

appid

String

否

94****11

已开通需要的语音合成服务的 AppId。

注意

使用火山语音技术服务时，该参数为必填。

cluster

String

否

volcano_tts

具体语音合成服务对应的 Cluster ID。

音频生成-语音合成服务：volcano_tts；
大模型音频生成-大模型语音合成服务：volcano_tts；
大模型音频生成-大模型声音复刻 2.0 服务（字符版）：volcano_icl。
大模型音频生成-大模型声音复刻 2.0 服务（并发版）：volcano_icl_concurr。
默认值为音频生成-语音合成服务对应的 Cluster ID: volcano_tts。

Audio

参数	类型	是否必选	示例值	描述
voice_type	String	否	`BV002_streaming`	具体语音合成服务开通音色 ID。音频生成-语音合成服务：所选音色的 Voice_type；大模型音频生成-大模型语音合成服务：所选音色的 Voice_type；大模型音频生成-大模型声音复刻 2.0 服务：所选音色的声音 ID。默认值为音频生成-语音合成服务通用女声音色 Voice_type：`BV002_streaming`。
speed_ratio	Float	否	`1.0`	语速。语音合成服务：取值范围为`[0.2,3]`，默认值为 `1.0`，通常保留一位小数即可。大模型声音复刻服务：取值范围为`[0.8,2]`，默认值为 `1.0`，通常保留一位小数即可。
volume_ratio	Float	否	`1.0`	音量。取值范围为 `[0.1,3]`，默认值为 `1.0`，通常保留一位小数即可。注意仅使用语音合成服务时生效。
pitch_ratio	Float	否	`1.0`	音高。取值范围为 `[0.1,3]`，默认值为 `1.0`，通常保留一位小数即可。注意仅使用语音合成服务时生效。

MiniMaxTTSConfig

参数	类型	是否必选	示例值	描述
Authorization	String	否	`eyJhbG****SUzI1N`	API 密钥。前往 Minimax 账户管理-接口密钥获取。注意使用 MiniMax 服务时，该参数为必填。
Groupid	String	否	`983*****669`	用户所属组 ID。前往 Minimax 账号信息-基本信息获取。注意使用 MiniMax 服务时，该参数为必填。
model	String	否	`speech-01-turbo`	发起请求的模型版本： `speech-01-turbo`：最新模型，拥有出色的效果与时延表现。 `speech-01-240228`：稳定版本模型，效果出色。 `speech-01-turbo-240228`：稳定版本模型，时延更低。注意使用 MiniMax 服务时，该参数为必填。
voice_setting	Object of VoiceSetting	否	`-`	音频配置。
URL	String	否	`https://api.minimax.chat/v1/t2a_v2`	请求语音合成 URL，取值固定为：`https://api.minimax.chat/v1/t2a_v2`。注意使用 MiniMax 服务时，该参数为必填。
pronunciation_dict	Object of PronunciationDict	否	`-`	特殊标注配置。可对特殊文字、符号指定发音。
timber_weights	Array of TimberWeights	否	`-`	合成音色权重设置。可通过该参数设置多种音色混合，并调整每个具体音色权重。最多支持 4 种音色混合。注意 `timber_weights`与 `VoiceSetting.voice_id`必须设置其中一个。
stream	Boolean	否	`false`	是否开启流式输出。 `false`：不开启流式输出。 `true`：开启流式输出。默认值为 `false`。
language_booststring	String	否	`auto`	增强指定小语种/方言场景下的语音表现。不同场景下取值及含义如下：不明确小语种类型：`auto`。取值为`auto`时，模型将自主判断小语种类型。小语种： `Spanish`：西班牙语 `French`：法语 `Portuguese`：葡萄牙语 `Korean`：韩语 `Indonesian`：印度尼西亚语 `German`：德语 `Japanese`：日语 `Italian`：意大利语 `auto`：自动模式方言： `Chinese,Yue`：粤语。`Chinese,Yue`仅当`MiniMaxTTSConfig.model`=`speech-01-turbo`时生效。默认值为空。

VoiceSetting

参数	类型	是否必选	示例值	描述
speed	Float	否	`1.0`	语速，取值越大，语速越快。取值范围为 `[0.5,2]`，默认值为`1.0`。
vol	Float	否	`1.0`	音量，取值越大，音量越高。取值范围为`（0,10]`，默认值为 `1.0`。
pitch	Float	否	`0`	语调。取值范围为`[-12,12]`，且必须为整数。默认值为 `0`，表示原音色输出。
voice_id	String	否	`male-qn-jingying`	系统音色编号/复刻音色编号。系统音色可前往 voice_setting.voice_id查询。克隆音色参看FAQ。注意 `voice_id` 与 `timber_weights`必须设置其中一个。

PronunciationDict

参数	类型	是否必选	示例值	描述
tone	Array of String	否	`["燕少飞/(yan4)(shao3)(fei1)","达菲/(da2)(fei1)"，"omg/oh my god"]`	替换需要特殊标注的文字、符号及对应的注音。替换发音（调整声调/替换其他字符发音），格式如下： `["燕少飞/(yan4)(shao3)(fei1)","达菲/(da2)(fei1)"，"omg/oh my god"]` 声调用数字代替，一声（阴平）为1，二声（阳平）为2，三声（上声）为3，四声（去声）为4），轻声为5。

TimberWeights

参数	类型	是否必选	示例值	描述
voice_id	String	否	`male-qn-jingying`	音色编号。当前仅支持系统音色，可前往 voice_setting.voice_id查询。
weight	Integer	否	`1`	权重。取值为整数，单一音色取值占比越高，合成音色越像。取值范围为`[1,100]`。

ARKLLMConfig

参数	类型	是否必选	示例值	描述
Mode	String	是	`ArkV3`	大模型名称，该参数固定取值： `ArkV3`。
EndPointId	String	否	`epid****212`	推理接入点。使用方舟大模型时必填。可参看在线推理创建或查询推理接入点。注意 EndPointId 与 BotId 不可同时填写，若同时填写，则 EndPointId 生效。
BotId	String	否	`botid****212`	智能体 ID。使用方舟智能体时为必填。可前往控制台创建或查询智能体 ID。
MaxTokens	Integer	否	`1024`	输出文本的最大 token 限制。默认值为 `1024`。
Temperature	Float	否	`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` 大模型，预设 SystemMessages 和 UserMessages 各两条，询问第 10 个问题时，需保证预设的两条 SystemMessages、预设的两条 UserMessages 与第八、九、十条问题的总长度之和不得超过 8k。
WelcomeSpeech	String	否	`Hello`	智能体启动后的欢迎词。
Tools	Array of ToolParam	否	`-`	使用 Function calling 功能时，模型可以调用的工具列表。仅支持函数作为工具，提供模型生成的 JSON 输入函数列表。该功能使用方法参看Function calling。注意 Function calling 功能不支持和联网插件、知识库插件同时开启。
Prefill	Boolean	否	`false`	将 ASR 中间结果提前送入大模型进行处理以降低延时。开启后会产生额外模型消耗。 `true`：开启。 `false`：关闭。默认值为 `false`。注意该功能不能和 Function calling 功能同时使用。

ToolParam

参数	类型	是否必选	示例值	描述
type	String	否	`function`	工具类型，当前仅支持取值 `function`。
function	Object of FunctionDefinition	否	`-`	模型可以调用的工具列表。

FunctionDefinition

参数	类型	是否必选	示例值	描述
name	String	是	`get_current_weather`	函数的名称。
description	String	否	`获取指定城市的天气信息`	对函数用途的描述，供模型判断何时以及如何调用该工具函数。
parameters	JSON Map	否	`{ "type": "object", "properties": { "location": { "type": "string", "description": "城市，如：北京", }, }, "required": ["location"], }`	函数请求参数，以 JSON Schema 格式描述。具体格式请参考 JSON Schema 文档。

ThirdPartyLLMConfig

参数	类型	是否必选	示例值	描述
Mode	String	是	`CustomLLM`	大模型名称。使用第三方大模型时，该参数固定取值： `CustomLLM`。
URL	String	否	`https://test.com/path/to/app`	第三方大模型 URL，需要使用 HTTPS 域名。若需要验证第三方大模型 URl 是否符合火山引擎 OpenAPI 标准，请参看对话式 AI 第三方大模型接口验证。注意如需使用 http 域名进行测试，Feature 参数的值必须为`{\"Http\":true}`，且此时 Qos 无法保证。
ModelName	String	否	`name1`	第三方大模型名称。
APIKey	String	否	`pat*****123231`	Bearer Token 认证方式的大模型 token。
MaxTokens	Integer	否	`1024`	输出文本的最大 token 限制。默认值为 `1024`。
Temperature	Float	否	`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` 大模型，预设 SystemMessages 和 UserMessages 各两条，询问第 10 个问题时，需保证预设的两条 SystemMessages、预设的两条 UserMessages 与第八、九、十条问题的总长度之和不得超过 8k。
WelcomeSpeech	String	否	`Hello`	智能体启动后的欢迎词。
Feature	String	否	`{\"Http\":true}`	该参数固定取值：`{\"Http\":true}`，表示使用 HTTP 域名进行测试。
Prefill	Boolean	否	`false`	将 ASR 中间结果提前送入大模型进行处理以降低延时。开启后会产生额外模型消耗。 `true`：开启。 `false`：关闭。默认值为 `false`。注意该功能不能和 Function calling 功能同时使用。

SubtitleConfig

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
DisableRTSSubtitle	Boolean	否	`false`	是否关闭房间内字幕回调。 `true`：关闭字幕。 `false`：开启字幕。默认值为 `false`。字幕功能详细说明参看实时字幕。
ServerMessageUrl	String	否	`https://example-domain.com/vertc/subtitle`	接收字幕结果的 URL 地址。接收结果的 URL 必须以域名开头。如果 URL 为 HTTPS 域名，请确保该域名 SSL 证书合法且完整。 `ServerMessageUrl` 和 `ServerMessageSignature` 均填写正确才能开启服务端字幕功能。
ServerMessageSignature	String	否	`b46ab5f1d8ad6a`	鉴权签名。你可传入该鉴权参数，在接收到字幕结果后，与结果中的`signature`字段值进行对比以进行鉴权验证。

DisableRTSSubtitle

Boolean

否

false

是否关闭房间内字幕回调。

true：关闭字幕。
false：开启字幕。
默认值为 false。字幕功能详细说明参看实时字幕。

ServerMessageUrl

String

否

https://example-domain.com/vertc/subtitle

接收字幕结果的 URL 地址。
接收结果的 URL 必须以域名开头。如果 URL 为 HTTPS 域名，请确保该域名 SSL 证书合法且完整。
ServerMessageUrl 和 ServerMessageSignature 均填写正确才能开启服务端字幕功能。

ServerMessageSignature

String

否

b46ab5f1d8ad6a

鉴权签名。
你可传入该鉴权参数，在接收到字幕结果后，与结果中的signature字段值进行对比以进行鉴权验证。

返回参数

本接口无特有的返回参数。公共返回参数请见返回结构。
其中返回值 Result 仅在请求成功时返回 ok,失败时为空。

请求示例 1

使用方舟大模型和火山引擎语音技术时：

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": {
            "IgnoreBracketText": [
                1,
                2
            ],
            "Provider": "volcano",
            "ProviderParams": {
                "app": {
                    "appid": "94****11",
                    "cluster": "volcano_tts"
                },
                "audio": {
                    "voice_type": "BV002_streaming",
                    "speed_ratio": 1,
                    "volume_ratio": 1,
                    "pitch_ratio": 1
                }
            }
        },
        "LLMConfig": {
            "Mode": "ArkV3",
            "EndPointId": "epid****212",
            "MaxTokens": 1024,
            "Temperature": 0.1,
            "TopP": 0.3,
            "SystemMessages": [
                "你是小宁，性格幽默又善解人意。你在表达时需简明扼要，有自己的观点。"
            ],
            "UserMessages": [
                "user:\"你是谁\"",
                "assistant:\"我是问答助手\"",
                "user:\"你能干什么\"",
                "user:\"我能回答问题\""
            ],
            "HistoryLength": 3,
            "WelcomeSpeech": "Hello",
        }
    }
}

返回示例 1

{
    "Result": "ok",
    "ResponseMetadata": {
        "RequestId": "202****420",
        "Action": "StartVoiceChat",
        "Version": "2024-06-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}

请求示例 2

使用第三方大模型和 MiniMax 时：

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": {
            "IgnoreBracketText": [
                1,
                2
            ],
            "Provider": "minimax",
            "ProviderParams": {
                "Authorization": "eyJhbG****SUzI1N",
                "Groupid": "983*****669",
                "model": "speech-01-turbo",
                "URL": "https://api.minimax.chat/v1/t2a_v2",
                "stream": false,
                "voice_setting": {
                    "speed": 1.0,
                    "vol": 1.0,
                    "pitch": 1.0
                },
                "pronunciation_dict": {
                    "tone": [
                        "处理/(chu3)(li3)",
                        "危险/dangerous"
                    ]
                },
                "language_boost": "Chinese,Yue",
                "timber_weights": [{
                    "voice_id": "male-qn-jingying",
                    "weight": 70
                },
                {
                    "voice_id": "wumei_yujie",
                    "weight": 30
                }
                ]
            }
        },
        "LLMConfig": {
            "Mode": "CustomLLM",
            "URL": "https://test.com/path/to/app",
            "MaxTokens": 1024,
            "Temperature": 0,
            "TopP": 0.3,
            "SystemMessages": [
                "你是小宁，性格幽默又善解人意。你在表达时需简明扼要，有自己的观点。"
            ],
            "UserMessages": [
                "user:\"你是谁\"",
                "assistant:\"我是问答助手\"",
                "user:\"你能干什么\"",
                "user:\"我能回答问题\""
            ],
            "HistoryLength": 3,
            "WelcomeSpeech": "Hello"
        }
    }
}

返回示例 2

{
    "Result": "ok",
    "ResponseMetadata": {
        "RequestId": "202****420",
        "Action": "StartVoiceChat",
        "Version": "2024-06-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}