服务端API

更新时间：2025-11-03

总览

本章节介绍了百度云大模型互动OpenAPI的的REST风格接口，包括请求的组成部分，如何通过这些组成部分构造一个请求。您可以参看本章节，来构造HTTP请求调用对应的OpenAPI 。

请求结构

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!"
}
            

创建大模型互动实例

接口描述

创建并启动大模型互动实例接口。

请求语法

                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
config	String	否	RequestBody	大模型互动实例级别配置，格式是json对象序列化后的string类型

config中支持参数说明

config中字段	类型	描述	示例值
location	String	用户位置信息	北京市海淀区
role	String	简单角色	“你是旅游达人”
sceneRole	String	复杂场景人设	实例复杂场景人设名称（需要对应用提前设置场景人设名称和对应的prompt）
tts_sayhi	String	招呼语	主动打招呼的话，“你好！”
lang	String	设置语言，支持普通话（zh）、英语（en）、广东话（zh_yue)、四川话（zh_sc）、日语（ja）、西班牙语（es）、俄语（ru）、韩语（ko）、越南语（vi）、德语（de）、法语（fr）、阿拉伯语（ar），具体见多语言接入	枚举类型如下：enum {zh,en,zh_yue,zh_sc,ja,es,ru,ko,vi,de,fr,ar}
audiocodec	String	设置音频格式	可选类型如下：opus(默认值)、pcmu、 g722、raw、raw16k
disable_voice_auto_int	bool	关闭自动打断	设置为true则关闭自动打断
interruption_words	String	开启自动打断并且配置了在线打断词，只有在线打断词可以打断当前TTS播报。在线打断词可以配置多个，使用","分割。如果是暂停聊天状态，可通过在线打断词或者”继续聊天“唤醒服务。	小度小度,你好小度
interruption_answer	String	在线打断回复词。配置了在线打断词后，可以通过配置interruption_answer来定制固定的回复词。默认为空，打断时回复词为大模型返回，唤醒时快速回复我在。	我在呢
dfda	bool	关闭静音包填充	设置为true，则不下发静音包填充的音频数据
tts	String	可选配置，空缺表示使用百度云控制台配置。实例级别tts配置名称。支持内置类型和三方tts，三方类型tts按需需要传入对应的鉴权参数	目前支持DEFAULT（内置）, VOLC, XUNFEI, BAIDU
tts_url	String	可选配置，空缺表示使用百度云控制台配置。实例级别tts配置详情，格式是以tts名称拼接tts详细配置json 对象序列化的string	{"tts_url": "DEFAULT{\"vcn\": \"1000240\",\"vol\": 2.0,\"spd\": 1.0}"}
llm	String	实例级别大模型配置，支持内置模型（无需传参数）和三方模型（OPENAI协议、百度AB、阿里百炼、腾讯元宝、扣子、Dify等。参见：第三方服务集成步骤指引)
llm_url	String	实例级别大模型配置，支持内置模型（无需传参数）和三方模型（OPENAI协议、百度AB、阿里百炼、腾讯元宝、扣子、Dify等。参见：第三方服务集成步骤指引)
llm_cfg	String	实例级别大模型配置，支持内置模型（无需传参数）和三方模型（OPENAI协议、百度AB、阿里百炼、腾讯元宝、扣子、Dify等。参见：第三方服务集成步骤指引)
llm_token	String	实例级别大模型配置，支持内置模型（无需传参数）和三方模型（OPENAI协议、百度AB、阿里百炼、腾讯元宝、扣子、Dify等。参见：第三方服务集成步骤指引)
e2ellm_mode	String	选填项：语音端到端模型配置，需要走端到端语音模型才配置此项	设置为 audio_to_audio
e2ellm_sample_rate	int	端到端语音模型返回的音频采样率，只有配置了e2ellm_mode才有效果	目前只支持24000
user_id	String	业务侧用户的唯一id	enterprise-1-toy-1
asr_vad_append	bool	ASR断句后容许追加	默认true, 可以配置false
asr_vad	int	ASR断句时长(单位毫秒)	默认200ms, 可以配置其他时长
asr_vad_level	int	ASR说话过程中说话人音量检测	默认45, 可以配置其他level
voice_fp_url	String	声纹检测配置	默认空， {"enableRegisterPrint":false,"enableAudioEmbedding":true,"voicePrintInterrupt":1,"similarity":[0.3,0.35,0.4,0.51]} "enableRegisterPrint" 自动注册首句音频做为参考音频 "enableAudioEmbedding" 音频声纹开关 "voicePrintInterrupt" 声纹做为打断 0 关闭， 1打开 "similarity" 声纹匹配阈值
remote_music_player	bool	音乐播放是否支持云端播放	默认false，可以配置为true

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

请求示例

                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\"}"
    }
}
            

响应头域

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

响应参数

参数名	类型	描述
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
            

服务端打断大模型互动实例播报

接口描述

打断大模型互动实例播报

请求语法

                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

接口描述

服务端提供接口用来发送指定消息给sdk

请求语法

                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	角色的名称（需注意该角色必须已在控制台上创建）
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": "yourAppId",
    "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": "yourAppId",
  "nick_name": "小明",
  "user_id": "yourUserId",
  "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": "yourAppId",
  "nick_name": "小明",
  "user_id": "yourUserId",
  "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": "yourAppId",
    "user_id": "yourUserId",
    "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	是	RequestBody	大模型互动应用ID
user_id	String	是	RequestBody	用户唯一标识

请求示例

                JSON
                
            

                GET /api/v1/voiceprint/list  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",
    "user_id": "yourUserId"
}
            

响应头域

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

响应参数

响应示例

                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	大模型互动实例不存在

客户端SDK

音色管理

RTC 实时音视频

服务端API

总览

请求结构

请求示例

错误信息

创建大模型互动实例

接口描述

请求语法

请求头域

请求体

config中支持参数说明

tts_url中支持的参数配置

请求示例

响应头域

响应参数

响应示例

错误响应码

停止大模型互动实例

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

服务端打断大模型互动实例播报

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

错误响应码

大模型互动实例发消息给sdk

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

错误响应码

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

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

错误响应码

注册声纹

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

错误响应码

删除声纹

接口描述

请求语法

请求头域

请求体

请求示例

响应头域

响应参数

响应示例

错误响应码

查询声纹列表

接口描述

请求语法