服务端API

更新时间：2026-05-29

总览

本章节介绍百度云大模型互动 OpenAPI 的 REST 风格接口，包括请求的组成部分及如何构造请求。
OpenAPI接口域名为：rtc-aiagent.baidubce.com

请求结构

HTML

1// 请求
2{HTTPMethod} {协议}://{serviceId}.baidubce.com/?请求参数
3RequestHeader
4RequestBody
5
6=================================================================================================================================
7
8// 返回
9{HTTP-Version} {Status-Code} {Reason-Phrase}
10ResponseHeader
11ResponseBody

名称	是否必选	描述	示例值
HTTPMethod	是	百度云请求 Method	POST
协议	是	百度云请求支持通过HTTP或HTTPS协议进行请求通信。为了获得更高的安全性，推荐您使用HTTPS协议发送请求。	https
serviceId	是	服务名	rtc-aiagent
请求参数	否	请求参数	xx
RequestHeader	是	百度云OpenAPI 的公共请求头	authorization
RequestBody	否	接口自定义请求参数，每个 OpenAPI 自定义的请求参数。	app_id
ResponseHeader	是	接口返回结果的 header	x-bce-request-id
ResponseBody	否	接口返回的业务数据	ai_agent_instance_id

请求示例

                JSON
                
            

                POST /api/v1/aiagent/stopAIAgentInstance  HTTP/1.1

/** RequestHeader **/
authorization:bce-auth-v1/ffab11fa2b5a4f698d159af2c23f556e/2024-06-06T03:00:20Z/1800/host/3fbe830c1e67389523e2ff09f47ec59c4ed723dcea22018569a3aec968cdfbe6
Content-Type:application/json; charset=utf-8
x-bce-date:2015-04-27T08:23:49Z
host:rtc-aiagent.baidubce.com

/** RequestBody **/
{
    "业务请求参数": "json格式"
}

=================================================================================================================================

/** ResponseHeader **/
HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
date: Wed, 03 Dec 2014 06:42:19 GMT
content-Type: application/json;charset=UTF-8

/** ResponseBody **/
{
    "requestId":"1214cca7-4ad5-451d-9215-71cb844c0a50"
}
            

错误信息

所有错误除了使用HTTP状态码以外，应同时在内容中至少包含下表的参数。各服务应该适当地增加错误时返回的参数以方便定位。

参数名	类型	说明
requestId	String	导致该错误的requestId
code	String	字符串，用于表示具体错误类型
message	String	有关该错误的详细说明

示例：

                JSON
                
            

                {
    "requestId":"ae2225f7-1c2e-427a-a1ad-5413b762957d",
    "code":"AppParamNotValid",
    "message":"app not exist!"
}
            

创建大模型互动实例(互动智能体)

接口描述

创建并启动大模型互动服务(互动智能体)实例接口。
应用调用该接口后，云端创建好互动服务实例，并返回ai_agent_instance_id、token(24小时内有效)等重要信息；端侧使用返回信息连接到互动服务实例，进行交互。
通过该接口设定互动服务实例的工作参数，主要包括有：人设角色、语种、对话模式、语音预增强、ASR参数、第三方模型服务、TTS参数、意图参数等。没有指定参数则采用控制台对APPID的设定及参数默认值。
互动服务实例配置包括APPID级（在控制台界面配置）、实例级别（本接口传递），参数冲突以实例级优先。
注：1、服务实例创建后，要求端侧在30秒内连接，否则服务实例超时回收。 2、该接口建议在服务端调用，否则存在安全隐患。

请求语法

                JSON
                
                POST /api/v{version}/aiagent/generateAIAgentCall HTTP/1.1
host: rtc-aiagent.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

除公共头域外，无其它特殊头域。

请求体

名称	类型	是否必选	参数位置	描述
app_id	String	是	RequestBody	大模型互动应用ID
instance_type	String	否	RequestBody	互动实例类型（默认是VoiceChat）语音互动: VoiceChat （注：多模态互动也是该类型）数字人互动：DigitalHuman 实时语音翻译：RealtimeTranslation 小龙虾互动：ClawChat
config	String	否	RequestBody	大模型互动实例级别配置，格式是json对象序列化后的string类型

config中支持参数说明

config中字段	类型	描述	注意事项及示例值
location	String	用户地理位置字符描述形式。该参数与：gis、ip_to_location参数三选一	例：北京市海淀区
gis	String	地理经纬度数值描述形式。该参数与：location、ip_to_location参数三选一	例：上海市黄浦区gis:"31.235,121.480"
ip_to_location	bool	是否自动将客户端ip转地理位置字符描述。地理信息可能存在不准的情况该参数与：location、gis参数三选一	默认值false
role	String	角色描述短语。可与参数sceneRole并存，建议是sceneRole的简单描述。该参数只允许是短语，如语文教师、可爱的猫咪、办公助手小明等；不能是复杂的角色prompt，不建议超过32字符	例：“旅游达人”
sceneRole	String	角色名称。可与参数role并存。取值是控制台定义的角色名称，要求严格对应。该参数与sceneRoleCfg二选一。要求预先在控制台中创建好角色，通过该参数传入在服务实例中生效使用	例:“北极熊”
sceneRoleCfg	SceneRoleConfig	临时角色定义及配置。建议大小不超过2K。与sceneRole二选一，只在该服务实例中生效。支持name、prompt、model等参数，详见下文SceneRoleConfig结构	示例：{"sceneRoleCfg":{"name":"小度熊","prompt":"你是智能聊天助手小度熊，性格：热情且富有情感，能陪用户谈天说地，回复简明扼要。","model":"DEFAULT"}}。
tts_sayhi	String	招呼语端连接上智能体服务后，服务实例主动向端推送招呼语，并TTS播报。	例:“你好！”
lang	String	语言参数支持普通话（zh）、英语（en）、广东话（zh_yue)、四川话（zh_sc）、苏州话（zh_su）、日语（ja）、西班牙语（es）、俄语（ru）、韩语（ko）、越南语（vi）、德语（de）、法语（fr）、阿拉伯语（ar）、印尼语（id）、泰语（th）、马来语（ms）、葡萄牙语（pt）、乌兹别克语（uz）、波兰语（pl）、波斯语（fa），具体见多语言接入	取值为该范围之一:[zh,en,zh_yue,zh_sc,zh_suja,es,ru,ko,vi,de,fr,ar,id,th,ms]
audiocodec	String	下行(服务器->端)音频编码及采样率	可选如下：opus(vbr 采样率48K,默认值)、opus_cbr_8000、opus_cbr_16000、opus_cbr_24000、opus_cbr_32000、opus_cbr_48000、pcmu、 g722、raw、raw16k。其中opus_cbr_8000表示opus编码、cbr模式、采样率为8000
audio_bitrate	int	下行(服务器->端)音频码率	注意：该参数只有在audiocodec值为opuscbr*情况下才能生效，建议是采样率的1～2倍，例：采样率为16K，建议码率为32K（部分端解码器限定码率除外）
aoco	bool	设置下行(服务器->端)opus编码时是否使用celt only编码, 配合opus编码使用	全写为：audio_opus_celtonly
aopt	int	设置下行(服务器->端)opus编码时编码包的大小, 配合opus编码使用	全写为：audio_opus_ptime 可取值为10，20，40，60 单位是ms
disable_voice_auto_int	bool	关闭云上自动打断。控制TTS在播报过程中，是否可以被用户输入语音或文本打断播报	设置为true则关闭自动打断
interruption_words	String	在线打断词开启自动打断并且配置了在线打断词，只有在线打断词可以打断当前TTS播报。在线打断词可以配置多个，使用","分割。如果是暂停聊天状态，可通过在线打断词或者”继续聊天“唤醒服务。	小度小度,你好小度
interruption_answer	String	在线打断回复词，配合interruption_words使用。配置了在线打断词后，可以通过配置interruption_answer来定制固定的回复词。默认为空，打断时回复词为大模型返回，唤醒时快速回复我在。	我在呢
auto_pause_secs	Integer	自动暂停时长 (auto_pause_secs),配合interruption_words使用。当用户超过设定秒数未说话时，服务将自动暂停。用户可通过打断词或说“继续聊天”恢复对话。设置为 0 则关闭此功能。	60
dfda	bool	是否关闭下行（服务器->端）填充静音包。	全写为：disable_fill_dummy_audio 设置为true，则不下发静音包填充的音频数据。该参数目的是兼容部分端播放器在接收的音频包不连续时（在没有TTS下发时，服务器没发送空音包）导致的播放卡顿。建议该参数设置为true, 经实测能降低语音交互延时300ms+
tts	String	可选配置，空缺表示使用百度云控制台配置。 tts配置名称。支持内置类型和三方tts，三方类型tts按需需要传入对应的鉴权参数	目前支持DEFAULT（内置）, VOLC, XUNFEI, BAIDU（百度云官网支持的单独tts服务，使用时需要设置对应的鉴权参数，和DEFAULT不同）, CCLONE（通过接口进行C端复刻音色使用此类型）
tts_url	Json	可选配置，配合参数tts使用，空缺表示使用百度云控制台配置。格式是以tts名称为前缀拼接tts详细配置json 对象序列化的string（注意：前缀一定要和tts支持的类型完全一致，且要和tts参数同时存在）	{"tts_url": "DEFAULT{\"vcn\": \"1000240\",\"vol\": 2.0,\"spd\": 1.0}"}
tts_end_delay_ms	int	tts播报结束服务器下发TTS_END_SPEAKING事件的延迟	当前默认延迟是2.1秒，如果需要TTS_END_SPEAKING更快到来，可以调小，如50毫秒
llm	String	使用第三方大模型服务配置。使用默认模型服务无需传该参数；控制台配置了第三方模型参数无需传参数。第三方模型（OPENAI协议、百度AB、阿里百炼、腾讯元宝、扣子、Dify等。参见：第三方服务集成步骤指引)
llm_url	String	使用第三方大模型服务url配置，配合参数llm使用使用默认模型服务无需传该参数；控制台配置了第三方模型参数无需传参数。第三方模型（OPENAI协议、百度AB、阿里百炼、腾讯元宝、扣子、Dify等。参见：第三方服务集成步骤指引)
llm_cfg	String	使用第三方大模型服务cfg参数，配合参数llm使用使用默认模型服务无需传该参数；控制台配置了第三方模型参数无需传参数。第三方模型（OPENAI协议、百度AB、阿里百炼、腾讯元宝、扣子、Dify等。参见：第三方服务集成步骤指引)
llm_token	String	使用第三方大模型服务token参数，配合参数llm使用使用默认模型服务无需传该参数；控制台配置了第三方模型参数无需传参数。第三方模型（OPENAI协议、百度AB、阿里百炼、腾讯元宝、扣子、Dify等。参见：第三方服务集成步骤指引)
e2ellm_mode	String	使用"语音端到端模型"配置。与"默认模型服务"、"第三方模型服务"三选一	启用则设置固定值: "audio_to_audio"
e2ellm_sample_rate	int	使用"语音端到端模型"配置项，指定语音的采样率。配合参数e2ellm_mode使用，目前只支持24000 ｜
user_id	String	应用设定的唯一user_id，用于标识不同用户，要求appid应用级别内唯一，建议使用手机号码或设备串号等	例子：“enterprise-1-toy-0000001”
content_used_db	String	使用内容资源私有库的名称。该库采用私有音乐库接口维护。参见:最佳实践	多个库使用","分割。如不设置，默认使用系统默认自带音乐库（aiagentDb）。eg:指定自己的库和默认库 “db1,aigentDb”
asr_long_audio_mode	bool	是否使用asr按键模式。	设置为true则互动实例为asr按键收音模式，此模式配合设备侧按键对话收音、结束按键对话收音事件使用事件消息格式的对话模式设置消息。三种语音对话模式最佳实践
asr_vad_append	bool	是否开启多次ASR断句后的“粘句”功能。多次ASR断句后识别的文字，在限定时间（默认1.5秒）组合一起，作为一个query送到大模型服务生成回复，关闭该功能可能降低交互延时，建议开启。	默认true, 可选配置false
asr_vad	int	云端ASR断句等待的时长(单位：毫秒)，建议设置为最短200ms，并组合开启"粘句"功能使用。	默认200ms, 建议取值范围：200～2000ms. 儿童说话慢，建议适当增加该值，该值增大会增加对话延时。
asr_vad_level	int	用户声音能量阀值。服务器计算端上传音频的能量值，当超过与该值则下发事件：VOICE_COMING	默认45, 范围是0 ~ 100，。；该值计算规则：音频采样求和然后取log10生成的曲线；量化到0~100；
voice_fp_url	json	声纹配置	默认空， {"firstSentenceRegistration":false,"enable":true,"interruptMode":0,"enableSyncWait":false, "similarity":[0.18,0.22,0.30,0.40]} "firstSentenceRegistration" 自动注册首句音频做为参考音频(首句说话音频时长不够5秒，后面说话内容继续累计。) "enable" 音频声纹开关 "enableSyncWait" 三方模型使用声纹时候是否容许同步等待（最大等待时长100ms) "interruptMode" 声纹做为打断 0 关闭， 1打开 "similarity" 声纹匹配阈值详见声纹最佳实践
remote_music_player	bool	是否开启云端播放功能。云端播放实现自动下载有声资源、自动转码、流化流控；可以降低端侧的计算量、解决音频格式兼容性等问题，建议开启云播方式。云播最佳实践	默认false，可以配置为true
emotionRecognitionCfg	json	情绪功能配置	{"enable":true,"injectToLLM":false,"ttsWithEmotion":false, "emotionList":["中性", "高兴"]} 详见情感识别最佳实践
cloud_3A_url	json	云端3A（AEC、AGC、ANS）功能配置。详见云端音频3A最佳实践	{"AEC":{"enable":false,"maxEchoDelayMs":500,"eHeadESMs":3000,"delayThreshold":0.2,"initDuration":2.5,"dtThreshold":0.25},"ANS":{"enable":true},"AGC":{"enable":false,"maxVolume":60,"extraGain":0}}。
tts_enable_fast_send	bool	是否开启云TTS/云播加速下发	默认为false，开启时会对每一句TTS播报及云播放音乐进行加速下发，可一定程度提高音频下行弱网抗性、降低首token时延，但也可能增大打断时延。使用时需配置合理的端侧缓冲区大小、加速持续时长及加速倍率(默认持续2s、 2.0倍率下发)。
tts_fast_send_second	int	TTS/云播加速下发持续时长仅tts_enable_fast_send开启有效	默认为2s，对每一句TTS或云播放音频前若干秒进行加速发送，建议设置2~3s。
tts_fast_send_ratio	float	TTS/云播加速发送倍率，仅tts_enable_fast_send开启有效	默认为2.0倍加速，按照指定的倍率进行音频加速下发，建议设置1.2~2.0倍速。
etbt	bool	是否开启LLM回复的文本和tts语音播报同步对齐	全写为：enable_ttsdk_sync_by_tts
mcp_servers	json	mcp_servers 配置。详细参见最佳实践	`{"mcp_servers":[{"name":"baidu-weather","headers":{"Authorization":"Bearer xxxxx"},"protocol":"HttpStreamable","endpoint":"https://qianfan.baidubce.com/v2/tools/baidu-weather/mcp"}]}`
transSourceLang	String	翻译源语言, 仅在翻译模式即instance_type=RealtimeTranslation时生效	"transSourceLang":"zh-CN"
transTargetLang	String	翻译目标语言, 仅在翻译模式即instance_type=RealtimeTranslation时生效	"transTargetLang":"en-US"
transServiceVersion	String	翻译服务版本, 仅在翻译模式即instance_type=RealtimeTranslation时生效	默认为空，使用百度大脑及其翻译服务。设置值为V2时，如"transServiceVersion":"V2"，采用自研翻译服务。两个版本的语言参数设置不同，详情请参考实时语音翻译最佳实践
transAutoDetect	bool	翻译检测模式，该参数仅在翻译transServiceVersion=V2时生效，表示是否开启双语言自动检测，默认开启, 关闭后只能实现单向翻译，如中文-俄语	"transAutoDetect":false
enable_visual	bool	打开视频通道，仅sdk接入有效	默认false，sdk方式接入时，使用多模态（视觉理解及生图）功能，媒体上传、下发走udp数据通道
screen_width	int	生图场景，设置生成图片宽度,范围[360, 2048]，极速模型[360, 512]（支持sdk、ws接入方式）	默认为640
screen_height	int	生图场景，设置生成图片高度,范围[360, 2048]，极速模型[360, 512]（支持sdk、ws接入方式）	默认为480
intentCfg	Object	意图路由配置。用于配置RAG知识库、话题等意图，参考知识库使用最佳实践	参考知识库使用最佳实践
hotwords	String	ASR配置热词（优先级高于传热词表）	多个热词使用英文“,”分隔。示例：热词1,热词2,热词3
human	object	开启主动任务，从音视频中感知出诸如有人出现、抽烟、玩手机等事件	示例 {"human":{"senses":{"auto_register":true,"visual":{"enable":true},"audio":{"enable":true},"tasks":["task_8a3f1b2c4d5e6f7a","task_9b4e2c3d5e6f7a8b"]}}}
openclawConfig	json	OpenClaw 小龙虾接入配置	示例：{"enabled":true,"clawGatewayUrl":"gatewayUrl","claws":[{"type":"openclaw","name":"my-claw","claw_token":"xxx"}]} 详情请参考接入小龙虾OpenClaw最佳实践
variables	json	动态变量初始化参数	示例：{"variables":{"room_name":"客厅","device_name":"空调"}} 详情请参考动态变量最佳实践

tts_url中支持的参数配置

tts_url中字段	类型	描述	示例值
vcn	String	实例级别tts发音人	test_voice
vol	Double	实例级别tts音量配置，内置tts类型范围[0.5~2.0]表示基础声音的倍数，三方tts使用对应配置参数	0.5
spd	Double	实例级别tts音速配置，内置tts类型范围[0.5~2.0]表示基础音速的倍数，三方tts使用对应配置参数	0.5
apid	String	实例级别tts外部账号id配置。type为DEFAULT时非必要，其余按需	your_apid
apikey	String	实例级别tts外部账号鉴权key、token等。type为DEFAULT时非必要，其余按需	your_apikey
apisk	String	实例级别tts外部账号sk配置。type为DEFAULT时非必要，其余按需	your_apisk

mcp_servers 中支持的参数配置

字段	类型	描述	示例值
`[].name`	String	服务唯一标识名称	`baidu-weather`
`[].endpoint`	String	MCP Server 服务地址	`https://qianfan.baidubce.com/...`
`[].protocol`	String	协议类型（支持 `HttpStreamable`, `SSE`）	`HttpStreamable`
`[].headers`	Map	HTTP 请求头	`{"Authorization":"Bearer xxxxx"}`
`[].response_filter`	Map	JSON 响应字段过滤映射	详见MCP Server接入指南

SceneRoleConfig结构

参数名	类型	是否必需	描述
name	String	是	自定义复杂角色名称
prompt	String	是	自定义复杂角色prompt，该字段有长度限制，在`创建大模型互动实例`接口中最大长度为6000，在`切换大模型互动实例的角色`接口中最大长度为3000。
model	String	否	自定义复杂角色使用的模型，默认为DEFAULT，暂时只在`创建大模型互动实例`接口中支持。 model支持传递的参数值: - 预置人设模型：DEFAULT - 千帆-IPCharacter：QIANFAN_IPCHARACTER - ERNIE-4.5-Turbo：ERNIE_4_5_TURBO - DeepSeek-V3.2：DEEPSEEK_3_2

human结构

参数名	类型	是否必须	描述
sense	Object	否	感知配置
+ auto_register	Boolean	否	是否允许一句话语音注册感知任务，默认false
+ visual	Object	否	视觉感知配置
++ enable	Boolean	否	是否开启视觉感知，默认false
+ audio	Object	否	声音感知配置
++ enable	Boolean	否	是否开启声音感知，默认false
+ tasks	List	否	感知任务ID列表，任务的相关接口见主动任务管理

请求示例

                JSON
                
            

                POST /api/v1/aiagent/generateAIAgentCall  HTTP/1.1
host: rtc-aiagent.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}
x-bce-request-id: {bce-request-id}
{
    "app_id": "yourAppId",
    "config": "{\"llm\" : \"\", \"llm_token\" : \"no\", \"lang\" : \"zh\", \"tts\": \"DEFAULT\", \"tts_url\":\"DEFAULT{\\\"vcn\\\": \\\"\\\",\\\"vol\\\": 0.1,\\\"spd\\\": 1.1, \\\"apid\\\": \\\"\\\", \\\"apikey\\\": \\\"\\\"}\", \"user_id\": \"enterprise-1-toy-1\",\"content_used_db\": \"db1,db2\"}"
    }
}
            

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名	类型	描述
ai_agent_instance_id	long	大模型互动实例ID
instance_type	String	大模型互动实例类型
context	Object	大模型互动实例上下文
+cid	Long	大模型互动实例sdk使用数据通信ID
+token	String	大模型互动实例sdk使用数据通信token

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb
date: Mon, 05 Sep 2022 03:25:43 GMT
transfer-encoding: chunked
content-type: application/json;charset=UTF-8
cache-control: no-cache
{
    "ai_agent_instance_id": 222,
    "instance_type": "VoiceChat",
    "context": {
        "cid": 1,
        "token": "xxx"
    }
}
            

错误响应码

Code	Message	HTTP Status Code	说明
AppParamNotValid	app not exist!	400	大模型应用不存在
AIAgentInstanceIdGenerateException	generate ai agent instance id error	400	创建大模型互动实例ID异常
AIProxyCreateInstanceFailedException	create ai proxy instance failed	400	启动大模型互动实例异常

停止大模型互动实例（互动智能体）

接口描述

停止大模型互动实例接口。释放互动实例资源。

请求语法

                JSON
                
                POST /api/v{version}/aiagent/stopAIAgentInstance HTTP/1.1
host: rtc-aiagent.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

除公共头域外，无其它特殊头域。

请求体

名称	类型	是否必选	参数位置	描述
app_id	String	是	RequestBody	大模型互动应用ID
ai_agent_instance_id	Long	是	RequestBody	大模型互动实例ID

请求示例

                JSON
                
            

                POST /api/v1/aiagent/stopAIAgentInstance  HTTP/1.1
host: rtc-aiagent.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}
x-bce-request-id: {bce-request-id}
{
    "app_id": "yourAppId",
    "ai_agent_instance_id": 123456
}
            

响应头域

除公共头域外，无其它特殊头域。

响应参数

N/A

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb
date: Mon, 05 Sep 2022 03:25:43 GMT
transfer-encoding: chunked
content-type: application/json;charset=UTF-8
cache-control: no-cache
            

打断互动服务实例当前TTS播报并播报新内容

接口描述

打断大模型互动实例TTS的当前播报，停止下发TTS音频数据。并控制服务端TTS播放传人的extra_msg内容。

请求语法

                JSON
                
                POST /api/v{version}/aiagent/interrupt HTTP/1.1
host: rtc-aiagent.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

除公共头域外，无其它特殊头域。

请求体

名称	类型	是否必选	参数位置	描述
app_id	String	是	RequestBody	大模型互动应用ID
ai_agent_instance_id	Long	是	RequestBody	大模型互动实例ID
extra_msg	String	否	RequestBody	打断时携带的播报消息

请求示例

                JSON
                
            

                POST /api/v1/aiagent/interrupt  HTTP/1.1
host: rtc-aiagent.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}
x-bce-request-id: {bce-request-id}
{
    "app_id": "yourAppId",
    "ai_agent_instance_id": 123456,
    "extra_msg": "打断后播报您好"
}
            

响应头域

除公共头域外，无其它特殊头域。

响应参数

N/A

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb
date: Mon, 05 Sep 2022 03:25:43 GMT
transfer-encoding: chunked
content-type: application/json;charset=UTF-8
cache-control: no-cache
            

错误响应码

Code	Message	HTTP Status Code	说明
AIProxyInstanceNotExistException	ai proxy instance not exist	400	大模型互动实例不存在

发消息给端侧(SDK端或WebSocket端）

接口描述

发送消息给端侧。

请求语法

                JSON
                
                POST /api/v{version}/aiagent/sendMsg HTTP/1.1
host: rtc-aiagent.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

除公共头域外，无其它特殊头域。

请求体

名称	类型	是否必选	参数位置	描述
app_id	String	是	RequestBody	大模型互动应用ID
ai_agent_instance_id	Long	是	RequestBody	大模型互动实例ID
message	String	是	RequestBody	自定义消息

请求示例

                JSON
                
            

                POST /api/v1/aiagent/sendMsg  HTTP/1.1
host: rtc-aiagent.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}
x-bce-request-id: {bce-request-id}
{
    "app_id": "yourAppId",
    "ai_agent_instance_id": 123456,
    "message": "发送给sdk的消息内容"
}
            

响应头域

除公共头域外，无其它特殊头域。

响应参数

N/A

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb
date: Mon, 05 Sep 2022 03:25:43 GMT
transfer-encoding: chunked
content-type: application/json;charset=UTF-8
cache-control: no-cache
            

错误响应码

Code	Message	HTTP Status Code	说明
AIProxyInstanceNotExistException	ai proxy instance not exist	400	大模型互动实例不存在

切换互动实例的角色（音色）

接口描述

切换互动服务实例中的角色（音色）。

请求语法

                JSON
                
                PUT /api/v{version}/aiagent/instances/operation?switchSceneRole HTTP/1.1
host: rtc-aiagent.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

请求头域

除公共头域外，无其它特殊头域。

请求体

名称	类型	是否必选	参数位置	描述
app_id	String	是	RequestBody	大模型互动应用ID
ai_agent_instance_id	Long	是	RequestBody	大模型互动实例ID
scene_role	String	否	RequestBody	角色的名称（需注意该角色必须已在控制台上创建）
scene_role_cfg	SceneRoleConfig	否	RequestBody	自定义复杂角色配置，详见本页SceneRoleConfig结构。建议大小不超过2K。目前在切换角色接口中只支持设置name、prompt参数，不支持设置model参数。
tts	String	否	RequestBody	tts的配置，取值等价于创建大模型互动实例接口的tts_url
tts_sayhi	String	否	招呼语	切换音色后的招呼语

请求示例

                JSON
                
            

                PUT /api/v1/aiagent/instances/operation?switchSceneRole  HTTP/1.1
host: rtc-aiagent.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}
x-bce-request-id: {bce-request-id}
{
    "app_id": "YOUR_APP_ID",
    "ai_agent_instance_id": 123456,
    "scene_role": "英语口语老师"
    "tts": "DEFAULT{\"vcn\":\"1000063\"}",
    "tts_sayhi": "你好，我是一名英语口语老师"
}
            

响应头域

除公共头域外，无其它特殊头域。

响应参数

N/A

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb
date: Mon, 05 Sep 2022 03:25:43 GMT
transfer-encoding: chunked
content-type: application/json;charset=UTF-8
cache-control: no-cache
            

错误响应码

Code	Message	HTTP Status Code	说明
AIProxyInstanceNotExistException	ai proxy instance not exist	400	大模型互动实例不存在
NoSuchSceneRole	"No such scene role=scene_role	400	切换的角色不存在

注册用户声纹信息

接口描述

服务端提供接口用来注册声纹信息

请求语法

                JSON
                
                POST /api/v{version}/voiceprint/register HTTP/1.1	
host: rtc-aiagent.baidubce.com	
content-type: application/json	
authorization: <bce-authorization-string>

请求头域

除公共头域外，无其它特殊头域。

请求体

名称	类型	是否必选	参数位置	描述
app_id	String	是	RequestBody	大模型互动应用ID
nick_name	String	是	RequestBody	用户昵称，用于匹配时候返回信息
user_id	String	是	RequestBody	用户唯一标识
format	String	是	RequestBody	支持两种格式 PCM/WAV，要求是单声道16k
file_base64	String	是	RequestBody	文件base64

请求示例

                JSON
                
            

                POST /api/v1/voiceprint/register  HTTP/1.1	
host: rtc-aiagent.baidubce.com	
content-type: application/json	
authorization: {bce-authorization-string}	
x-bce-request-id: {bce-request-id}	
{	
  "app_id": "YOUR_APP_ID",	
  "nick_name": "小明",	
  "user_id": "YOUR_USER_ID",	
  "format": "wav",	
  "file_base64": "xxx"	
}	
            

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名	类型	描述
app_id	String	大模型互动实例ID
nick_name	String	用户昵称
user_id	String	用户唯一标识
vp_id	String	声纹id

响应示例

                JSON
                
            

                HTTP/1.1 200 OK	
x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb	
date: Mon, 05 Sep 2022 03:25:43 GMT	
transfer-encoding: chunked	
content-type: application/json;charset=UTF-8	
cache-control: no-cache	
{	
  "app_id": "YOUR_APP_ID",	
  "nick_name": "小明",	
  "user_id": "YOUR_USER_ID",	
  "vp_id": "vp_id_xxxxxx"	
}	
            

错误响应码

Code	Message	HTTP Status Code	说明
AIAgentAppNotFoundException	ai agent app not found	404	大模型互动实例不存在
IllegalVoiceprintFileFormatException	illegal voiceprint file format	400	声纹音频格式不支持
BceValidationException	xxx may not be null	400	缺少必需参数

删除用户声纹信息

接口描述

服务端提供接口用来删除用户的声纹信息

请求语法

                JSON
                
                DELETE /api/v{version}/voiceprint/delete HTTP/1.1	
host: rtc-aiagent.baidubce.com	
content-type: application/json	
authorization: <bce-authorization-string>

请求头域

除公共头域外，无其它特殊头域。

请求体

名称	类型	是否必选	参数位置	描述
app_id	String	是	RequestBody	大模型互动应用ID
user_id	String	是	RequestBody	用户唯一标识
vp_ids	List	是	RequestBody	批量删除user_id下的声纹列表

请求示例

                JSON
                
            

                DELETE /api/v1/voiceprint/delete  HTTP/1.1	
host: rtc-aiagent.baidubce.com	
content-type: application/json	
authorization: {bce-authorization-string}	
x-bce-request-id: {bce-request-id}	
{	
    "app_id": "YOUR_APP_ID",	
    "user_id": "YOUR_USER_ID",	
    "vp_ids": ["vp_id_1", "vp_id_2", "vp_id_3"]	
}	
            

响应头域

除公共头域外，无其它特殊头域。

响应参数

响应示例

                JSON
                
            

                HTTP/1.1 200 OK	
x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb	
date: Mon, 05 Sep 2022 03:25:43 GMT	
transfer-encoding: chunked	
content-type: application/json;charset=UTF-8	
cache-control: no-cache	
            

错误响应码

Code	Message	HTTP Status Code	说明
AIAgentAppNotFoundException	ai agent app not found	404	大模型互动实例不存在
BceValidationException	xxx may not be null	400	缺少必需参数

查询声纹用户列表

接口描述

服务端提供接口用来查询声纹列表

请求语法

                JSON
                
                GET /api/v{version}/voiceprint/list HTTP/1.1	
host: rtc-aiagent.baidubce.com	
content-type: application/json	
authorization: <bce-authorization-string>

请求头域

除公共头域外，无其它特殊头域。

请求体

名称	类型	是否必选	参数位置	描述
app_id	String	是	RequestParam	大模型互动应用ID
user_id	String	是	RequestParam	用户唯一标识

请求示例

                JSON
                
                GET /api/v1/voiceprint/list?app_id=YOUR_APP_ID&user_id=YOUR_USER_ID  HTTP/1.1	
host: rtc-aiagent.baidubce.com	
content-type: application/json	
authorization: {bce-authorization-string}	
x-bce-request-id: {bce-request-id}

响应头域

除公共头域外，无其它特殊头域。

响应参数

响应示例

                JSON
                
            

                HTTP/1.1 200 OK	
x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb	
date: Mon, 05 Sep 2022 03:25:43 GMT	
transfer-encoding: chunked	
content-type: application/json;charset=UTF-8	
cache-control: no-cache	
{	
  "data": [	
    {	
      "id": "vp_id",	
      "app_id": "xxx",	
      "nick_name": "name",	
      "user_id": "uid",	
      "format": "wav",	
      "timestamp": 1762159935	
    }	
  ]	
}	
            

错误响应码

Code	Message	HTTP Status Code	说明
AIAgentAppNotFoundException	ai agent app not found	404	大模型互动实例不存在

评价此篇文章

有帮助没帮助

快速入门

音色管理

RTC 实时音视频

服务端API

总览

请求结构

请求示例

错误信息

创建大模型互动实例(互动智能体)

接口描述

请求语法

请求头域

请求体

config中支持参数说明

tts_url中支持的参数配置

mcp_servers 中支持的参数配置

SceneRoleConfig结构

human结构

请求示例

响应头域

响应参数

响应示例

错误响应码

停止大模型互动实例（互动智能体）

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

打断互动服务实例当前TTS播报并播报新内容

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

错误响应码

发消息给端侧(SDK端或WebSocket端）

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

错误响应码

切换互动实例的角色（音色）

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

错误响应码

注册用户声纹信息

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

错误响应码

删除用户声纹信息

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

错误响应码