# 接口说明

对数字人开放平台接口进行管理和对接。

# 使用须知

  1. 客户需要先开通开放平台相应能力并购买套餐，获取到API Key和API Secret后妥善保存。如何开通 (opens new window)
  2. 通过API Key和API Secret进行接入并获取access_token，后续所有请求接口的地址需要追加access_token参数，access_token有效时间默认2小时。
  3. 作品合成成功后，用户需要下载保存，防止丢失，API服务端默认24小时后进行作品清除。
  4. 开放平台接口统一访问地址：https://meta.guiji.ai

# 交互流程

image.png

# 作品结果获取方式

开放平台支持查询和回调两种方式来监听作品的最终结果。

  1. 查询
    当作品合成请求提交成功后，客户端可通过“***列表”接口或“***详情”接口进行对作品合成状态的更新。
  2. 回调
    作品合成接口均提供了callbackUrl回调地址的属性，客户端只需要传公网可访问的回调地址即可，开放平台作品合成成功或失败后都会通过该地址通知客户端，回调参数请参考“***回调”接口。

# access_token获取

  1. 构造签名
    签名规则如下，该签名用来获取access_token使用。
    规则：通过APIKey、时间戳（毫秒）、APISecret三者拼接后md5加密生成。MD5加密后的结果类型：32位小写。
    如：md5(APIKey+ 时间戳（毫秒）+ APISecret)

  2. 获取access_token

接口地址：

/openapi/oauth/token

请求方式：GET

请求数据类型：application/json

响应数据类型：application/json

# 接口描述：

从开放平台获取access_token。

# 请求参数：
字段 类型 是否必须 备注
appId String Y API Key
timestamp String Y 当前时间戳，精确到毫秒
sign String Y 生成的签名
grant_type String Y 认证类型(固定值‘sign’)

示例：

https://meta.guiji.ai/openapi/oauth/token?grant_type=sign&timestamp=1648429269823&sign=3fe58596ec5edc297876e00f4e4b1a49&appId=TPbMPQeD4U2dJgRY62PCRnSz
# 响应参数：
字段 类型 是否必须 备注
code String Y 返回的状态码，为0表示成功
success Boolean Y 成功/错误
data Json Y JSONObject
  access_token String Y access_token值
  expires_in Integer Y 过期时间，单位“秒”

示例：

{
  "code": "0",
  "success": true,
  "data": {
    "access_token": "99568c59-eb7e-4feb-b546-078f2fe9d5c6",
    "expires_in": 7199
  }
}

# 公共返回参数

开放平台得到access_token和其他请求数据集合后，会先进行安全校验等验证，一系列验证通过后便会处理完成这次发送过来的数据请求，平台返回的参数格式如下：

字段 类型 是否必须 备注
code String Y 返回的状态码，为0表示成功
success Boolean Y 是否成功
message String N 成功/错误的描述信息
data Object N 数据

# 公共状态码

状态码 描述
0 成功
40001 内部异常
40002 access_token无效
40003 access_token超时
40010 余额不足
40011 不合法的音频地址
40012 不合法的音频时长
40013 不合法的文件大小
40014 缺少必要文件
40015 缺少必要参数
40016 文件上传失败
40017 文件下载失败
40018 文件不存在
40019 超出并发
40020 不支持的背景图片格式
40021 提交训练视频失败
40022 不合法的码率值
40023 不合法的分辨率值
40024 不合法的fps值
40025 模特不存在
40026 模特已过期
40027 不合法的视频格式