【千帆平台】使用AppBuilder零代码创建应用，然后通过OpenAPI方式调用应用

欢迎来到《小5讲堂》

这是《千帆平台》系列文章，每篇文章将以博主理解的角度展开讲解。

温馨提示：博主能力有限，理解水平有限，若有不对之处望指正！

前言
创建API密钥
调用文档
调用说明
新建会话
- 接口描述
- 权限说明
- 接口定义
- 请求结构
- 请求头域
- 请求参数
- 响应头域
- 响应参数
- [请求curl 示例](#请求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方式调用应用

目录

前言

创建API密钥

调用文档

调用说明

API服务域名

通信协议

字符编码

公共请求头

新建会话

接口描述

权限说明

接口定义

请求结构

请求头域

请求参数

响应头域

响应参数

请求curl 示例

正确响应示例

错误响应示例

缺少授权参数

缺少应用ID参数

无答复

响应成功

大模型对话

接口描述

权限说明

接口定义

请求结构

请求头域

请求参数

服务错误

权限错误

响应成功

实现代码

错误返回码说明

推荐文章