服务端API
更新时间：2025-06-13
总览
本章节介绍了百度云大模型互动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
1POST /api/v1/aiagent/stopAIAgentInstance HTTP/1.1
2
3/** RequestHeader **/
4authorization:bce-auth-v1/ffab11fa2b5a4f698d159af2c23f556e/2024-06-06T03:00:20Z/1800/host/3fbe830c1e67389523e2ff09f47ec59c4ed723dcea22018569a3aec968cdfbe6
5content-Type:application/json; charset=utf-8
6x-bce-date:2015-04-27T08:23:49Z
7host:rtc-aiagent.baidubce.com
8
9/** RequestBody **/
10{
11 "业务请求参数": "json格式"
12}
13
14=================================================================================================================================
15
16/** ResponseHeader **/
17HTTP/1.1 200 OK
18x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
19date: Wed, 03 Dec 2014 06:42:19 GMT
20content-Type: application/json;charset=UTF-8
21
22/** ResponseBody **/
23{
24 "requestId":"1214cca7-4ad5-451d-9215-71cb844c0a50"
25}错误信息
所有错误除了使用HTTP状态码以外，应同时在内容中至少包含下表的参数。各服务应该适当地增加错误时返回的参数以方便定位。
| 参数名 | 类型 | 说明 |
|---|---|---|
| requestId | String | 导致该错误的requestId |
| code | String | 字符串，用于表示具体错误类型 |
| message | String | 有关该错误的详细说明 |
示例：
JSON
1{
2 "requestId":"ae2225f7-1c2e-427a-a1ad-5413b762957d",
3 "code":"AppParamNotValid",
4 "message":"app not exist!"
5}创建大模型互动实例
接口描述
创建并启动大模型互动实例接口。
请求语法
JSON
1POST /api/v{version}/aiagent/generateAIAgentCall HTTP/1.1
2host: rtc-aiagent.baidubce.com
3content-type: application/json
4authorization: <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 | 设置语言 | 枚举类型如下：enum {zh,en} |
| audiocodec | String | 设置sdk音频格式 | 可选类型如下：raw（表示使用pcmu）、raw16k（表示使用g722） |
| disable_voice_auto_int | bool | 关闭自动打断 | 设置为true则关闭自动打断 |
| tts | String | 实例级别tts配置名称。支持内置类型和三方tts，三方类型tts按需需要传入对应的鉴权参数 | 目前支持DEFAULT（内置）, VOLC, XUNFEI, BAIDU |
| tts_url | String | 实例级别tts配置详情，格式是以tts名称拼接tts详细配置json 对象序列化的string | {"tts_url": "DEFAULT{\"vcn\": \"111\",\"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等。参见：第三方服务集成步骤指引) |
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
1POST /api/v1/aiagent/generateAIAgentCall HTTP/1.1
2host: rtc-aiagent.baidubce.com
3content-type: application/json
4authorization: {bce-authorization-string}
5x-bce-request-id: {bce-request-id}
6{
7 "app_id": "yourAppId",
8 "config": "{\"llm\" : \"\", \"llm_token\" : \"no\", \"lang\" : \"zh\", \"tts\": \"DEFAULT\", \"tts_url\":\"DEFAULT{\\\"vcn\\\": \\\"4103\\\",\\\"vol\\\": 0.1,\\\"spd\\\": 1.1, \\\"apid\\\": \\\"\\\", \\\"apikey\\\": \\\"\\\"}\"}"
9 }
10}响应头域
除公共头域外，无其它特殊头域。
响应参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ai_agent_instance_id | long | 大模型互动实例ID |
| instance_type | String | 大模型互动实例类型 |
| context | Object | 大模型互动实例上下文 |
| +cid | Long | 大模型互动实例sdk使用数据通信ID |
| +token | String | 大模型互动实例sdk使用数据通信token |
响应示例
JSON
1HTTP/1.1 200 OK
2x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb
3date: Mon, 05 Sep 2022 03:25:43 GMT
4transfer-encoding: chunked
5content-type: application/json;charset=UTF-8
6cache-control: no-cache
7{
8 "ai_agent_instance_id": 222,
9 "instance_type": "VoiceChat",
10 "context": {
11 "cid": 1,
12 "token": "xxx"
13 }
14}错误响应码
| 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
1POST /api/v{version}/aiagent/stopAIAgentInstance HTTP/1.1
2host: rtc-aiagent.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>请求头域
除公共头域外，无其它特殊头域。
请求体
| 名称 | 类型 | 是否必选 | 参数位置 | 描述 |
|---|---|---|---|---|
| app_id | String | 是 | RequestBody | 大模型互动应用ID |
| ai_agent_instance_id | Long | 是 | RequestBody | 大模型互动实例ID |
请求示例
JSON
1POST /api/v1/aiagent/stopAIAgentInstance HTTP/1.1
2host: rtc-aiagent.baidubce.com
3content-type: application/json
4authorization: {bce-authorization-string}
5x-bce-request-id: {bce-request-id}
6{
7 "app_id": "yourAppId",
8 "ai_agent_instance_id": 123456
9}响应头域
除公共头域外，无其它特殊头域。
响应参数
N/A
响应示例
JSON
1HTTP/1.1 200 OK
2x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb
3date: Mon, 05 Sep 2022 03:25:43 GMT
4transfer-encoding: chunked
5content-type: application/json;charset=UTF-8
6cache-control: no-cache服务端打断大模型互动实例播报
接口描述
打断大模型互动实例播报
请求语法
JSON
1POST /api/v{version}/aiagent/interrupt HTTP/1.1
2host: rtc-aiagent.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>请求头域
除公共头域外，无其它特殊头域。
请求体
| 名称 | 类型 | 是否必选 | 参数位置 | 描述 |
|---|---|---|---|---|
| app_id | String | 是 | RequestBody | 大模型互动应用ID |
| ai_agent_instance_id | Long | 是 | RequestBody | 大模型互动实例ID |
| extra_msg | String | 否 | RequestBody | 打断时携带的播报消息 |
请求示例
JSON
1POST /api/v1/aiagent/interrupt HTTP/1.1
2host: rtc-aiagent.baidubce.com
3content-type: application/json
4authorization: {bce-authorization-string}
5x-bce-request-id: {bce-request-id}
6{
7 "app_id": "yourAppId",
8 "ai_agent_instance_id": 123456,
9 "extra_msg": "打断后播报您好"
10}响应头域
除公共头域外，无其它特殊头域。
响应参数
N/A
响应示例
JSON
1HTTP/1.1 200 OK
2x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb
3date: Mon, 05 Sep 2022 03:25:43 GMT
4transfer-encoding: chunked
5content-type: application/json;charset=UTF-8
6cache-control: no-cache错误响应码
| Code | Message | HTTP Status Code | 说明 |
|---|---|---|---|
| AIProxyInstanceNotExistException | ai proxy instance not exist | 400 | 大模型互动实例不存在 |
大模型互动实例发消息给sdk
接口描述
服务端提供接口用来发送指定消息给sdk
请求语法
JSON
1POST /api/v{version}/aiagent/sendMsg HTTP/1.1
2host: rtc-aiagent.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>请求头域
除公共头域外，无其它特殊头域。
请求体
| 名称 | 类型 | 是否必选 | 参数位置 | 描述 |
|---|---|---|---|---|
| app_id | String | 是 | RequestBody | 大模型互动应用ID |
| ai_agent_instance_id | Long | 是 | RequestBody | 大模型互动实例ID |
| message | String | 是 | RequestBody | 自定义消息 |
请求示例
JSON
1POST /api/v1/aiagent/sendMsg HTTP/1.1
2host: rtc-aiagent.baidubce.com
3content-type: application/json
4authorization: {bce-authorization-string}
5x-bce-request-id: {bce-request-id}
6{
7 "app_id": "yourAppId",
8 "ai_agent_instance_id": 123456,
9 "message": "发送给sdk的消息内容"
10}响应头域
除公共头域外，无其它特殊头域。
响应参数
N/A
响应示例
JSON
1HTTP/1.1 200 OK
2x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb
3date: Mon, 05 Sep 2022 03:25:43 GMT
4transfer-encoding: chunked
5content-type: application/json;charset=UTF-8
6cache-control: no-cache错误响应码
| Code | Message | HTTP Status Code | 说明 |
|---|---|---|---|
| AIProxyInstanceNotExistException | ai proxy instance not exist | 400 | 大模型互动实例不存在 |