接口通用说明
更新时间:2024-12-26
1. 接口鉴权
使用应用的 AppID、AppKey 和过期时间生成鉴权参数,在 Http 请求的 Header 传递鉴权参数进行鉴权。AppID 和 AppKey 的获取查看:平台操作指引
1.1 鉴权参数生成
鉴权参数格式:
AppId/Signature/ExpireTime
- AppId: 应用标识
- Signature: 使用 AppKey(应用秘钥) 对 AppId 和 ExpireTime(过期时间) 进行 hmac_sha256 (https://www.ietf.org/rfc/rfc2104.txt) 运算生成的签名信息
-
ExpireTime: 签名的过期时间
- 格式:使用ISO8601格式表示(ISO_OFFSET_DATE_TIME),具体的超时时间形如: 2011-12-03T10:15:30+01:00
- 根据业务场景设置,避免设置长期有效,以减小签名泄露的风险和影响
1.2 鉴权参数使用
需要加上以下的 HTTP 请求头,例如:
Authorization: s-pgewi73tzrtwt/e9649e34ed495c753bdf214c81d67d1166f26e66776d51482aa10f1c70bc65e2/2023-07-07T08:03:10.315Z
1.3 示例代码
(1)鉴权参数生成工具在线地址
https://open.xiling.baidu.com/token-gen-tool.html
(2)Postman Pre-script
var appId = " "; //填真实的appid
var appKey = " "; //填真实的appkey
var time = new Date(new Date().getTime() + 60 * 60 * 1000).toISOString();
const algorithm = CryptoJS.algo.SHA256;
const hmac = CryptoJS.algo.HMAC.create(algorithm, appKey);
hmac.update(appId + time);
var signature = hmac.finalize().toString();
pm.request.headers.add({
key: 'Authorization',
value: appId + "/" + signature + "/" + time
})
(3)Java demo
package com.baidu.acg.piat.digitalhuman.agent.demonstration.service;
import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
public class TokenDemo {
public static void main(String[] args) throws Exception {
String appId = " "; //填真实的appid
String appKey = " "; //填真实的appkey
// expiredTime eg: 2020-10-28T19:40:58.963441+08:00
String expiredTime = ZonedDateTime.now().plusHours(1).format(DateTimeFormatter.ISO_OFFSET_DATE_TIME);
// token eg: i-khpg99yk2j3gk/7dcefadebec0ee51f312ef1344d1d1cda9db4e35de7279ac7438823b5db96887/2020-10-28T19:40:58.963441+08:00
String authorization = appId + "/" + hmacSha256(appKey, appId + expiredTime) + "/" + expiredTime;
}
private static String hmacSha256(String key, String data) {
HmacUtils hmac = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, key);
return hmac.hmacHex(data);
}
}
(4)Python demo
import hmac
import hashlib
import datetime
def hmac_sha256(key, data):
return hmac.new(key.encode(), data.encode(), hashlib.sha256).hexdigest()
def main():
app_id = " " # 填真实的appid
app_key = "" # 填真实的appkey
# expiredTime eg: 2020-10-28T19:40:58.963441+08:00
expired_time = (datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=1)).isoformat()
# token eg: i-khpg99yk2j3gk/7dcefadebec0ee51f312ef1344d1d1cda9db4e35de7279ac7438823b5db96887/2020-10-28T19:40:58.963441+08:00
authorization = f"{app_id}/{hmac_sha256(app_key, app_id + expired_time)}/{expired_time}"
print(authorization)
if __name__ == "__main__":
main()
2. 通用信息
2.1 通用请求字段
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
requestId | string | 否 | 用于标识这次请求,长度不超过 50。用于问题排查,如果不填系统会随机生成并在响应中返回。 |
下文若无特殊说明,接口请求参数描述会省略通用字段。
2.2 通用响应字段
参数名 | 类型 | 描述 |
---|---|---|
requestId | string | 请求标识 |
code | int | 状态码,正常为 0 |
success | boolean | 是否正常返回 |
message | object | 提示信息 |
-- global | string | 正常返回时为 "success",异常时返回错误信息 |
result | object | 响应数据,泛型类型,可能为 null |
若无特殊说明,接口响应参数描述会省略这些通用字段,只针对 result 给出参数说明。
对于分页查询请求,接口响应的 result 字段会被 page 字段代替,说明如下:
参数名 | 类型 | 描述 |
---|---|---|
page | object | |
-- pageNo | int | 页码,从 1 开始 |
-- pageSize | int | 每页数量 |
-- totalCount | long | 数据总数 |
-- result | object [] | 当前页数据列表,泛型类型 |
2.3 通用错误码
错误码 | 描述 |
---|---|
0 | 正常返回 |
4911 | 找不到app信息,请确认appId是否输入正确 |
4913 | 无法访问API,可能是app没有绑定对应的组件,或url输入错误,或访问的人像不可用 |
10001 | 签名校验失败 |
10002 | 签名信息为空 |
10003 | 签名格式错误 |
10004 | 未识别错误的通用错误码 |
10005 | 请求体JSON解析失败,请确认是否是合法的JSON格式 |
10006 | 参数校验不通过 |
10011 | 没有购买对应的商品 |
14001 | 内部服务异常,请稍后再试 |
14002 | 内部服务异常,网络拥堵 |
2.4 任务回调接口
平台异步任务支持将任务完成事件发送到调用方提交任务填写的回调地址。回调消息只会发送一次,请求失败不会补发。POST 到调用方提交任务时指定的 URL,长度不超过 1000。
请求参数列表
参数名 | 类型 | 是否必填 | 描述 |
---|---|---|---|
requestId | string | 是 | 请求唯一标识,用于问题排查 |
type | string | 是 | 回调业务类型 ,比如单图视频合成任务,由具体业务接口定义 |
data | object | 是 | 回调业务数据,由具体业务接口定义 |