欢迎来到《小5讲堂》
这是《千帆平台》系列文章，每篇文章将以博主理解的角度展开讲解。
温馨提示：博主能力有限，理解水平有限，若有不对之处望指正！
目录
- 前言
- 创建API密钥
- 调用文档
- 调用说明
- API服务域名
- 通信协议
- 字符编码
- 公共请求头
- 新建会话
- 接口描述
- 权限说明
- 接口定义
- 请求结构
- 请求头域
- 请求参数
- 响应头域
- 响应参数
- 请求curl 示例
- 正确响应示例
- 错误响应示例
- 缺少授权参数
- 缺少应用ID参数
- 无答复
- 响应成功
- 大模型对话
- 接口描述
- 权限说明
- 接口定义
- 请求结构
- 请求头域
- 请求参数
- 服务错误
- 权限错误
- 响应成功
- 实现代码
- 错误返回码说明
- 推荐文章
前言
使用千帆平台的AppBuilder零代码构建应用非常简单，也提供界面进行体验和使用。
博主想把这个应用提供的API封装到自己后端，因此本篇文章就来聊聊如何调用API。
创建API密钥
使用说明
1.密钥为使用AppBuilder平台的重要凭证，因密钥长期有效，请勿放在浏览器或外部客户端代码中，请妥善管理分发。如意外泄露，在本页面删除密钥即可关闭对应访问入口。
2.删除密钥后，已删除密钥和旧地址将无法继续请求服务，并无法恢复，请谨慎操作。
调用文档
找到自己创建好的应用，点击发布详情，再点API调用，最后点O喷API的接口调用说明
接口调用说明地址：https://cloud.baidu.com/doc/AppBuilder/s/klv2eywua
调用说明
API服务域名
| Region | EndPoint | Protocol |
|---|---|---|
| all | qianfan.baidubce.com | HTTPS |
通信协议
API 调用遵循 HTTP 协议。
字符编码
可解析内容，所有 request/response body 内容目前均使用 UTF-8 编码。
公共请求头
以下列举部分
| 参数名称 | 描述 | 是否必填 | 示例 |
|---|---|---|---|
| Authorization | 请求签名(此签名为appbuilder平台密钥) | 必须 | Bearer bce-v3/ALTAK-LLfggwDKNJ3mZJFtIMYP8/0d******55cdb5e8b319f93b00fffc584cex8 |
| Content-Type | application/json;charset=utf-8 通用数据交互格式（默认） | 必须 | application/json;charset=utf-8 |
| multipart/form-data;charset=utf-8 支持图片、文件等上传，以及语音二进制流传输 | multipart/form-data;charset=utf-8 | ||
| text/event-stream;charset=utf-8 支持服务端向客户端推送服务、事件和消息通知的数据格式 | text/event-stream;charset=utf-8 |
HTTP协议的标准头域不在这里列出。公共头域将在下面的请求中出现。
新建会话
博主这里是使用C#代码进行调用
接口描述
该接口用于新增对话，对话的有效期为7天。超过之后可能无法使用，需要重新生成。
权限说明
Authorization需要填写密钥。
接口定义
完整地址：https://qianfan.baidubce.com/v2/app/conversation
| URL | /v2/app/conversation |
|---|---|
| Method | POST |
| Content-Type | application/json |
| Authorization | 请求签名(此签名为应用工作台密钥) |
请求结构
POST /v2/app/conversation HTTP/1.1
HOST: qianfan.baidubce.com
Authorization: authorization string
Content-Type: application/json
{
"app_id": "c5c7bfa8-97f6-48c0-97ac-689d1f6df6be"
}
请求头域
除公共头域外，无其它特殊头域。
请求参数
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| app_id | string | 是 | 指定需要创建对话的app_id，来源于个人空间-应用-应用ID |
响应头域
除公共头域外，无其它特殊头域。
响应参数
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| request_id | string | 是 | request_id |
| conversation_id | string | 是 | 对话id，可以用于后续调用，有效期为7天。 |
请求curl 示例
curl --location 'https://qianfan.baidubce.com/v2/app/conversation' \
--header 'Authorization: Bearer authorization string' \
--header 'Content-Type: application/json' \
--data '{
"app_id": "85036d8f-239c-469c-b342-b62ca9d696f6"
}'
正确响应示例
HTTP/1.1 200 OK
{
"request_id": "355a4f4e-a6d8-4dec-b840-7075030c6d22",
"conversation_id": "2370813b-5303-4a4f-b5cc-44f571121342"
}
错误响应示例
HTTP/1.1 401
{
"request_id": "ae2225f7-1c2e-427a-a1ad-5413b762957d",
"code": "PermissionDeniedError",
"message": "没有权限"
}
缺少授权参数
{“requestId”:“8cfe4b0a-7abd-4b8d-ab6f-093d7f0f7bfc”,“code”:216003,“message”:“Authentication error: ( Authorization or X-Appbuilder-Authorization header is required )”}
缺少应用ID参数
{“code”: “InvalidRequestArgumentError”, “message”: “request param app_id is required”, “request_id”: “65c6bf89-175f-4928-9dd1-9f4ad6a8656c”}
无答复
由于连接方在一段时间后没有正确答复或连接的主机没有反应，链接尝试失败。
原因：是博主自己网络问题，网络比较卡会出现这种情况
响应成功
{“request_id”: “b60e8917-98c0-4ca9-adc3-9dxxx”, “conversation_id”: “95914e46-d616-45e0-b8xxx”}
大模型对话
接口描述
该接口用于在一轮对话中向大模型发送消息。
权限说明
Authorization需要填写密钥。
接口定义
完整地址：https://qianfan.baidubce.com/v2/app/conversation/runs
| URL | /v2/app/conversation/runs |
|---|---|
| Method | POST |
| Content-Type | application/json |
| Authorization | 请求签名(此签名为应用工作台密钥) |
请求结构
POST /v2/app/conversation/runs HTTP/1.1
HOST: qianfan.baidubce.com
Authorization: authorization string
Content-Type: application/json
{
"app_id": "85036d8f-239c-469c-b342-b62ca9d696f6",
"query": "根据文件中的数据，统计这几所学校小学生有多少",
"stream": true,
"conversation_id": "355a4f4e-a6d8-4dec-b840-7075030c6d22",
"file_ids": [
"cdd1e194-cfb7-4173-a154-795fae8535d9"
]
}
请求头域
除公共头域外，无其它特殊头域。
请求参数
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| app_id | string | 是 | app_id，来源于个人空间-应用-应用ID。 |
| query | string | 是 | 用户query文字， 长度限制2000字符。 |
| stream | bool | 是 | 是否以流式接口的形式返回数据，默认false。 |
| conversation_id | string | 是 | 对话id，可通过新建会话接口创建。 |
| file_ids | list[string] | 否 | 如果在对话中上传了文件，可以将文件id放入该字段，目前只处理第一个文件。 |
服务错误
{“code”: “InternalServerError”, “message”: “The browser (or proxy) sent a request that this server could not understand.”, “request_id”: “6654ae9d-9ae8-4b40-95a9-cedb9xxx”}
权限错误
原因是stream参数设置成了true。
{“code”: “PermissionDeniedError”, “message”: “Permission denied at app_id 5a48d77f-23a7-4d87-9b87-b80c8ba463ca, conversation_id 86fc0e4f-981c-4bd7-8e30-39axxx”, “request_id”: “e9481c30-21af-41dd-9e59-bb629xxx”}
原因：拿错参数了， conversation_id参数拿成了request_id参数值，所以一直都是无权限获取。另一个原因是是否以流式接口的形式返回数据，默认false。
响应成功
实现代码
//令牌
string answer = string.Empty;
string conversation_id = string.Empty;
string app_id = "你的应用ID";
string Bearer = "API密钥";
// 新建会话 - 7天（建议保存起来，七天后再重新获取，省了每次去调用获取）
using (HttpClient client = new HttpClient())
{
// 设置请求的URL
string url = "https://qianfan.baidubce.com/v2/app/conversation";
var request = new HttpRequestMessage(HttpMethod.Post, url);
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Bearer);
var content = new StringContent("{\"app_id\":\"" + app_id + "\"}", Encoding.UTF8, "application/json");
request.Content = content;
HttpResponseMessage response = await client.SendAsync(request);
string responseBody = await response.Content.ReadAsStringAsync();
JObject jsonObject = JObject.Parse(responseBody);
dynamic dynamicObject = jsonObject;
conversation_id = dynamicObject.conversation_id;
}
// 大模型对话
using (HttpClient client = new HttpClient())
{
// 设置请求的URL
string url = "https://qianfan.baidubce.com/v2/app/conversation/runs";
var request = new HttpRequestMessage(HttpMethod.Post, url);
request.Headers.Add("Authorization", $"Bearer {Bearer}");
var content = new StringContent("{\"app_id\":\"" + app_id + "\",\"query\":\"你输入的文本\",\"stream\":false,\"conversation_id\":\"" + conversation_id + "\",\"file_ids\":[]}", Encoding.UTF8, "application/json");
request.Content = content;
HttpResponseMessage response = await client.SendAsync(request);
string responseBody = await response.Content.ReadAsStringAsync();
JObject jsonObject = JObject.Parse(responseBody);
dynamic dynamicObject = jsonObject;
answer = dynamicObject.answer;
}
错误返回码说明
| 错误码 | HTTP状态码 | 描述 | 说明 |
|---|---|---|---|
| InvalidRequestArgumentError | 400 | Invalid request argument | 请求参数错误 |
| PermissionDeniedError | 401 | Permission denied | 权限错误 |
| NotFoundResource | 404 | Not Found Resource | 账户、应用、模型、模版等无法找到 |
| InternalServerError | 500 | InternalServerError | 服务器内部错误 |
| QuotaLimitExceeded | 400 | Quota limit exceeded | 用户Quota超过限制 |
| TemplateValuesError | 400 | The value of the template does not match the template scheme | 模版参数校验错误 |
| QuotaLimitExpired | 400 | Quota limit expired | 用户Quota过期 |
| QianfanPermissionDeniedError | 400 | Qianfan Permission Denied Error | 千帆服务访问失败，一般是权限错误 |
| QianfanApiExpired | 400 | Qianfan Api Expired | 千帆服务过期 |
| AppStatusInvalidError | 400 | 应用体验地址已更新，请联系应用开发者获取最新地址 | 应用体验地址已更新，请联系应用开发者获取最新地址 |
| TokenStatusInvalidError | 400 | 鉴权失败，请联系应用开发者获取鉴权密钥 | 鉴权失败，请联系应用开发者获取鉴权密钥 |
| QueryParamInvalidError | 400 | query字段异常，请检查 | Query必填但未填值 |
| AccountNotExistError | 400 | 账户不存在 | app对应的账户不存在 |
| NoFileUploadedError | 400 | 上传文件时文件为空 | 对话中上传文件时文件为空 |
| TooManyFilesError | 400 | 文件上传时超过一个 | 对话中文件上传时超过一个 |
| FileTooLargeError | 400 | 文件上传大小超过限制 | 对话中文件上传大小超过限制 |
| UnsupportedFileTypeError | 400 | 文件类型不支持 | 对话中文件类型不支持 |
| InvalidFileError | 400 | 文件无效 | 对话中文件参数无效 |
| CreateAgentConversationError | 500 | 创建对话失败 | 对话中创建对话失败 |
| SdkTokenNotExistError | 400 | SDK 密钥不存在 | SDK 密钥不存在 |
| ChatError | 500 | 获取流式消息发生异常 | 仅在流式请求应答中出现 |
| RequestExpired | 400 | 请求超时 | 仅在传参x-bce-date时出现，有效时间30分钟 |
| InvalidHTTPRequestHeader | 400 | 无效的公共请求头参数 | 公共请求头参数错误 |
| 216003 | 401 | 鉴权错误 | nan |
推荐文章
【千帆平台】使用AppBuilder零代码创建应用，然后通过OpenAPI方式调用应用
【千帆平台】使用AppBuilder零代码创建应用，Excel表格数据转为Markdown格式文本
【千帆平台】AppBuilder工作流编排新功能体验之创建自定义组件
【千帆平台】AppBuildert工作流编排新功能体验之创建自定义组件
【千帆平台】使用AppBuilder三步手搓应用创建精准多轮对话agent之K12互动式练习题
【千帆平台】百度智能云千帆AppBuilder应用探索益智游戏之猜物小游戏
【人工智能】百度智能云千帆AppBuilder，快速构建您的专属AI原生应用
【人工智能】千帆平台创建和使用我的数据集，为什么需要数据集，有什么作用
【千帆平台】使用千帆大模型平台创建自定义模型调用API，贺岁灵感模型，文本对话
