API介绍

更新时间：2024-12-11

请求结构简介

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 通用数据交互格式（默认） multipart/form-data;charset=utf-8 支持图片、文件等上传，以及语音二进制流传输 text/event-stream;charset=utf-8 支持服务端向客户端推送服务、事件和消息通知的数据格式	必须	application/json;charset=utf-8 multipart/form-data;charset=utf-8 text/event-stream;charset=utf-8
x-bce-date	表示日期的字符串	可选	x-bce-date:2013-07-08T22%3A08%3A55Z 注意x-bce-date里面的冒号（`:`）已经被规范化成`%3A`。
Host	表示请求API的域名	可选	host: qianfan.baidubce.com
User-Agent	用户请求来源，SDK的请求，可由SDK指定对应的User-Agent 用户使用OpenAPI接入的情况，一般会被用户使用的工具自行填充	可选	python-requests/2.25.1(python) okhttp/4.10.0、ReactorNetty/1.0.17（java） curl/7.68.0（curl） appbuilder-sdk/0.4.1

HTTP协议的标准头域不在这里列出。公共头域将在下面的请求中出现。

公共响应头

参数名称	描述
x-bce-request-id	请求ID，后端生成，并自动设置到响应头域中
Content-Type	application/json;charset=utf-8 text/event-stream;charset=utf-8

最终请求形式

请求

最终的请求由以下几部分组成：

请求域名: qianfan.baidubce.com。
请求路径: 各个接口请求路径不同，详见具体接口详情。
请求方式: 支持RESTful风格的请求方式，本接口文档中只涉及到POST方式。
请求头: 包括鉴权信息在内的各个公共请求头。详细参考公共头。
请求body体：根据接口规定的RequestBody参数结构组成的json结构体。

示例：

curl --location 'https://qianfan.baidubce.com/v2/app/conversation' \
--header 'Authorization: Bearer authorization string' \
--header 'Content-Type: application/json' \
--data '{
    "app_id": "你的app_id"
}'

正确返回结果

使用JSON格式的结构体来描述一个请求返回的具体内容。作为示例，以下是一个正确的返回结果格式：

HTTP/1.1 200 OK
{
  "request_id": "355a4f4e-a6d8-4dec-b840-7075030c6d22",
  "conversation_id": "2370813b-5303-4a4f-b5cc-44f571121342"
}

错误返回结果

请求发生错误时通过respone body返回详细错误信息，遵循如下格式：

参数名	类型	说明
code	String	错误码
message	String	错误描述
request_id	String	本次请求ID

示例：

HTTP/1.1 401
{
  "request_id": "ae2225f7-1c2e-427a-a1ad-5413b762957d",
  "code": "PermissionDeniedError",
  "message": "没有权限"
}

错误返回码说明

错误码	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	鉴权错误
CancelAgentMessageError	500	取消消息失败	取消消息失败
RemoveError	500	删除失败	删除知识库失败
CreateError	500	新建失败	新建失败
UploadFileError	400	文件上传失败	文件上传失败
AgentQuotaExceededError	400	所选模型quota超出限额	所选模型quota超出限额
AgentQpsExceededError	400	所选模型qps超出限额	所选模型qps超出限额
AgentContentExceededError	400	输入字数超过模型上下文范围	输入字数超过模型上下文范围
AgentTokensExceededError	400	请求内容超过大模型tokens数限制	请求内容超过大模型tokens数限制

鉴权认证

通过密钥校验调用者的身份信息。在调用百度智能云千帆AI原生应用工作台提供的API前，必须先获取密钥。

前往API密钥，点击【新增密钥】按钮创建密钥，可自定义备注，支持一键复制操作。

密钥为使用AppBuilder平台的重要凭证，因密钥长期有效，请勿放在浏览器或外部客户端代码中，请妥善管理分发。如意外泄露，在本页面删除密钥即可关闭对应访问入口。
删除密钥后，已删除密钥和旧地址将无法继续请求服务，并无法恢复，请谨慎操作。

日期与时间规范

日期与时间的表示有多种方式。为统一起见，除非是约定俗成或者有相应规范的，凡需要日期时间表示的地方一律采用UTC时间，遵循ISO 8601，并做以下约束：

表示日期一律采用YYYY-MM-DD方式，例如2014-06-01表示2014年6月1日。
表示时间一律采用hh:mm:ss方式，并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
凡涉及日期和时间合并表示时，在两者中间加大写字母T，例如2014-06-01T23:00:10Z表示UTC时间2014年6月1日23点0分10秒。