数字人训练 API接入文档

一、接入准备

1.1 获取Accesskey

与我司商务合作后，我司会给客户硅语账号进行授权并且给出开放平台的AccessKey和SecretKey，客户可以通过AccessKey和SecretKey进行接入，请妥善保存。

1.2 开发以及联调测试

调用流程如下图

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

1.3 数字人训练结果查询

开放平台支持查询和回调两种方式来监听数字人训练的最终结果。

（1）、查询

数字人训练请求提交成功后，客户端可通过“3.4 训练任务查询列表”或“3.5 训练任务详情查询”进行对数字人训练状态的更新。

（2）、回调

数字人训练接口提供了callbackUrl回调地址的属性，客户端只需要传公网可访问的回调地址即可，开放平台数字人训练成功或失败后都会通过该地址通知客户端，回调参数请参考“3.3 训练任务回调接口”设计。

二、 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	不合法的视频格式
40028	文件上传失败
40030	背景地址不能访问
40031	音频地址不能访问
40032	发言人不存在
40033	文件地址不能访问
40040	声音合成失败
40041	视频解析失败
40042	不合法的MP3
40045	发言人已过期
40046	不合法的URL
40056	内容检测不通过
50010	扣款失败

三、 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.cn/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（Content-Type: application/json）

请求参数

字段	类型	必须	备注
id	number	N	训练任务ID，id为空表示提交新训练，id不为空表示更新训练
name	string	Y	数字人名称
videoUrl	string	Y	训练视频url，需公网可访问
callbackUrl	string		训练状态回调地址
level	Integer	N	定制套餐级别： 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（Content-Type: 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
}

3.4 训练任务列表查询

接口地址

/openapi/video/v2/training/pageList?access_token=ae4dad61-0dc5-47ad-be20-c51245db2769

请求方式

POST（Content-Type: application/json）

请求参数

字段	类型	必须	备注
page	integer	Y	请求页数
size	integer	Y	每页

示例

{
  "page": 1,
  "size": 2
}

返回结果

字段	类型	必须	备注
code	string	Y	返回的状态码，为0表示成功
message	string	Y	成功/错误的描述信息
data	string	Y	返回的jsonobject
pageSize	integer	N	页尺寸
pageNo	integer	N	页号
totalRecord	integer	N	总记录数
records	list	N	记录列表
id	string	Y	ID
title	string	Y	标题
videoUrl	string	Y	提交的待训练视频地址
status	integer	Y	训练状态 0或空-准备中 1训练中 2训练成功 3训练失败 4审核不通过
callbackStatus	integer	Y	回调状态 0或空-初始态 1-回调成功 2-回调失败
comment	string	Y	备注
robotId	integer	Y	训练完成模特ID
sceneId	integer	Y	训练完成场景ID
coverUrl	string	Y	模特封面地址
createTime	string	Y	创建时间
updateTime	string	Y	更新时间
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		示例图片

示例

{
  "code": "0",
  "message": "请求成功",
  "success": true,
  "data": {
    "pageSize": 1,
    "pageNo": 1,
    "totalRecord": 31,
    "records": [
      {
        "id": 84,
        "title": "zhang1222222",
        "videoUrl": "http://127.0.0.1/1179-2-train-20220819111631608.mp4",
        "status": 2,
        "callbackStatus": 2,
        "comment": "",
        "robotId": 4323,
        "sceneId": 4820,
        "createTime": "2022-08-23 12:14:48",
        "updateTime": "2023-02-14 17:43:09",
        "coverUrl": "http://127.0.0.1/b9e1a30e0c95ec26e6040091558c50cc.jpg",
        "robot": {
          "coverUrl": "http://127.0.0.1/b9e1a30e0c95ec26e6040091558c50cc.jpg",
          "robotName": "12.30",
          "id": 4323,
          "version": 0,
          "scene": {
            "coverUrl": "http://127.0.0.1/5a0d527d60ceec874af9a10f011e5dc0.png",
            "exampleUrl": "http://127.0.0.1/e4050efb5f0f52299d19c2b6bbccfcaf.mp4",
            "sceneName": "12.30",
            "id": 4820,
            "samplePictureUrl": "http://127.0.0.1/a76eeb78b6f4453a67c51b51e87e1703.png"
          }
        }
      }
    ]
  }
}

3.5 训练任务详情查询

接口地址

/openapi/video/v2/training/get/{id}?access_token=ae4dad61-0dc5-47ad-be20-c51245db2769

请求方式

GET

请求参数

字段	类型	必须	备注
id	integer	Y	提交的训练ID(路径参数)

返回结果

字段	类型	必须	备注
code	string	Y	返回的状态码，为0表示成功
message	string	Y	成功/错误的描述信息
data	string	Y	返回的jsonobject
id	string	Y	ID
title	string	Y	标题
videoUrl	string	Y	提交的待训练视频地址
status	integer	Y	训练状态 0或空-准备中 1训练中 2训练成功 3训练失败 4审核不通过
callbackStatus	integer	Y	回调状态 0或空-初始态 1-回调成功 2-回调失败
comment	string	Y	备注
robotId	integer	Y	训练完成模特ID
sceneId	integer	Y	训练完成场景ID
coverUrl	string	Y	模特封面地址
createTime	string	Y	创建时间
updateTime	string	Y	更新时间
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		示例图片

示例

{
  "code": "0",
  "message": "请求成功",
  "success": true,
  "data": {
    "id": 84,
    "title": "zhang1222222",
    "videoUrl": "http://127.0.0.1/1179-2-train-20220819111631608.mp4",
    "status": 2,
    "callbackStatus": 2,
    "comment": "",
    "robotId": 4323,
    "sceneId": 4820,
    "createTime": "2022-08-23 12:14:48",
    "updateTime": "2023-02-14 17:43:09",
    "coverUrl": "http://127.0.0.1/b9e1a30e0c95ec26e6040091558c50cc.jpg",
    "robot": {
      "coverUrl": "http://127.0.0.1/b9e1a30e0c95ec26e6040091558c50cc.jpg",
      "robotName": "12.30",
      "id": 4323,
      "version": 0,
      "scene": {
        "coverUrl": "http://127.0.0.1/5a0d527d60ceec874af9a10f011e5dc0.png",
        "exampleUrl": "http://127.0.0.1/e4050efb5f0f52299d19c2b6bbccfcaf.mp4",
        "sceneName": "12.30",
        "id": 4820,
        "samplePictureUrl": "http://127.0.0.1/a76eeb78b6f4453a67c51b51e87e1703.png"
      }
    }
  }
}

四、 相关协议

4.1 人工智能生成合成内容标识规范

（1）我们将依据相关法律法规，对人工智能生成合成内容添加相应标识（如在生成合成内容或者交互场景界面中添加的显式标识，采用技术措施在生成合成内容的文件元数据中添加的隐式标识）。您应确保您已仔细阅读并理解《人工智能生成合成内容标识办法》及其他相关的标识管理要求。您不得使用或尝试使用任何技术手段或其他方法删除、篡改、伪造、隐匿该等生成合成内容标识，不得为他人实施删除、篡改、伪造、隐匿该等生成合成内容标识行为提供工具或者服务，不得通过不正当标识手段损害他人合法权益。
（2）在特定场景下，为更好地满足您的使用需求，我们可能根据您的申请为您提供没有添加显式标识的人工智能生成合成内容。如您申请我们提供没有添加显式标识的生成合成内容的，您需承诺并保证：
①不利用该内容发布、传播任何虚假信息或从事其他任何违法违规活动；
②在发布或传播基于深度学习、虚拟现实、深度合成、生成式人工智能等新技术制作的非真实信息，或其他可能引发公众误解或混淆的信息内容时，应当以显著方式标识；
③在向第三方分享该内容或使用网络信息内容传播服务发布该内容或以其他方式使用该内容时，主动声明其为人工智能生成合成内容；
④遵守其他相关法律、法规、政策、办法的规定。
（3）如您违反上述约定，您应自行承担由此引起的所有责任，并赔偿由此给我们及第三方造成的全部损失（包括但不限于直接损失、间接损失、诉讼费、仲裁费、公证费、鉴定费、律师费、差旅费、保全费用、保全保险费、向任何第三方承担的责任、行政处罚、罚款等）。