# 数字人训练 API接入文档

# 一、接入准备

# 1.1 获取Accesskey

与我司商务合作后，我司会给客户进行开户，用户使用我司提供的账号密码登录我司平台后获取AccessKey, Secretkey进行接入对接，请妥善保存SecretKey。

# 1.2 开发以及联调测试

调用流程如下图

硅语平台生产地址：https://meta.guiji.ai (opens new window)

# 1.3 配置回调接口地址

在配置回调地址之后，开放平台会将任务过程事件信息推送至该回调接口。

在创建视频合成任务后，硅语开发平台会调用用户在平台配置的回调接口，进行合成结果的通知，详见3.7

# 二、 API对接方式

# 2.1 构造签名获取token

硅语平台获取签名的规则为：通过AccessKey、时间戳、加密生成得到的签名【MD5（AccessKey+时间戳+SecretKey）】，MD5结果取32位小写值，然后通过该签名请求硅语平台获取token，后续接口都需要加上该token进行请求，具体接口信息见第三部分API详细信息。

# 2.2 公共返回参数

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

字段	类型	是否必须	备注
code	string	Y	返回的状态码，为0表示成功
message	string	N	成功/错误的描述信息
data	object	N	返回的具体内容

# 2.3 公共错误码

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

# 三、 API接口

# 3.1 获取token接口

# 接口地址

/openapi/oauth/token

# 请求方式

GET

# 请求参数

字段	类型	是否必填	备注
appId	string	Y	Access 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	N	返回的JSONObject
access_token	string	N	返回的token值
expires_in	integer	N	Token过期时间，单位“秒”

示例：

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

# 3.2 训练视频提交

# 接口地址

/openapi/video/v2/create/training?access_token=55d1bc37-f960-4a9d-8c7d-5dc8c991c245

# 请求方式

POST Application/

# 请求参数

字段	类型	必须	备注
id	number	N	训练任务ID，id为空表示提交新训练，id不为空表示更新训练
name	string	Y	数字人名称
videoUrl	string	Y	训练视频url，需公网可访问
callbackUrl	string		训练状态回调地址
level	Integer	N	定制套餐级别：空或2.形象克隆-高阶版 358.形象克隆-S级-超清 359.形象克隆-E级 360.形象克隆-S级
greenScreen	Integer	N	是否是绿幕: 0.否 1.是

示例：

{
  "id": null,
  "videoUrl": "http://172.0.0.1/openapitraintest.mp4",
  "callbackUrl": "http://172.0.0.1/test/callback",
  "name": "test_training"
}

# 返回结果

字段	类型	必须	备注
code	string	Y	返回的状态码，为0表示成功
message	string	Y	成功/错误的描述信息
data	json	N	返回的jsonobject
trainingId	string	N	训练任务ID

示例：

{
    "code": "0",
    "message": "请求成功",
    "success": true,
    "data": {
        "trainingId": 101
    }
}

# 3.3 训练任务回调接口

# 接口地址

优先使用用户在接口中指定的回调地址，接口未指定的情况下，使用用户在平台配置的回调接口地址

# 请求方式

POST

Application/json

# 请求参数

字段	类型	必须	备注
taskType	string	Y	值为video-training表示视频训练任务回调
data	json	N	jsonobject
id	integer	Y	提交的任务ID
result	string	Y	success, fail
reason	string	N	失败原因
robotId	integer	N	模特ID
sceneId	integer	N	模特下场景ID
robot	json	Y	训练完成后的模特详情
id	integer	N	模特ID
robotName	string	N	模特名称
robotDesc	string	N	模特描述
coverUrl	string	N	模特封面地址
gender	integer	N	性别1男 2女
version	integer	N	类型0:2D 1:3D
age	integer	N	年龄
starSigns	integer	N	星座 1:'白羊座', 2:'金牛座', 3:'双子座', 4:'巨蟹座', 5:'狮子座', 6:'处女座', 7:'天秤座', 8:'天蝎座', 9:'射手座', 10:'摩羯座', 11:'水瓶座', 12:'双鱼座'
sceneList	list	N	数字人场景列表
id	integer	N	场景id(重要，视频合成必填ID)
sceneName	string		场景名称
exampleUrl	string		示例视频
coverUrl	string		封面地址
samplePictureUrl	string		示例图片

成功示例

{
  "taskType": "video-training",
  "data": {
    "result": "success",
    "id": 60,
    "robotId": 4323,
    "sceneId": 4820,
    "coverUrl": "http://172.0.0.1/b9e1a30e0c95ec26e6040091558c50cc.jpg",
    "robot": {
      "coverUrl": "http://172.0.0.1/b9e1a30e0c95ec26e6040091558c50cc.jpg",
      "id": 4323,
      "robotName": "12.30",
      "scene": {
        "coverUrl": "http://172.0.0.1/5a0d527d60ceec874af9a10f011e5dc0.png",
        "exampleUrl": "http://172.0.0.1/e4050efb5f0f52299d19c2b6bbccfcaf.mp4",
        "id": 4820,
        "proportion": "9:16",
        "resolution": "1080x1920",
        "robotId": 4323,
        "samplePictureUrl": "http://172.0.0.1/a76eeb78b6f4453a67c51b51e87e1703.png",
        "sceneCode": "369582992592965",
        "sceneName": "12.30",
        "sceneType": 0
      },
      "version": 0
    }
  }
}

失败示例

{
    "taskType": "video-training",
    "data": {
        "result": "fail",
        "reason": "审核不通过",
        "id": 63
    }
}

# 返回结果

字段	类型	必须	备注
code	string	Y	返回的状态码，为0表示成功

示例

{
    "code": "0",
    "message": "请求成功",
    "success": true
}