2D小样本数字人形象定制-专属口型接口
更新时间：2024-12-26
接口说明
接口调用域名：https://open.xiling.baidu.com
- 调用形象定制任务接口，提交真人拍摄视频，返回人像ID
- 接收任务结束的回调通知，或使用人像ID
查询人像定制任务状态 - 将定制人像用于视频合成、交互等场景
接口鉴权和通用字段说明请查阅：接口通用说明
调用本接口需要在平台购买 2D 小样本形象克隆组件商品并绑定到应用，操作说明参考：平台操作指引
接口列表
提交形象定制任务
接口说明
创建数字人训练任务，返回人像ID
接口协议
POST /api/digitalhuman/open/v1/figure/lite2d/train
Header Content-Type: application/json;charset=utf-8
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 数字人名称 命名要求： 1. 账户内名称唯一 2. 仅可输入中文、字母、数字、中划线、下划线 3. 不超过20个字符 |
| customizeType | string | 是 | 定制类型，固定填：LITE_2D_PERSONAL |
| gender | string | 是 | 性别 1. MALE（男） 2. FEMALE（女） |
| keepBackground | boolean | 是 | 是否保留底板视频背景 1. true：固定背景（保留原背景，后续驱动渲染不支持替换背景图） （1）【底板视频（templateVideoId）】【唇动视频（lipVideoId）】上传mp4格式的视频，【底板mask视频（maskVideoId）】无需上传 2. false：透明背景（后续驱动渲染支持替换任意背景图） （1）方案一（推荐）：【底板视频（templateVideoId）】【唇动视频（lipVideoId）】上传带alpha通道webm格式的视频，【底板mask视频（maskVideoId）】无需上传 （2）方案二：【底板视频（templateVideoId）】【唇动视频（lipVideoId）】【底板mask视频（maskVideoId）】均需上传mp4格式的视频 |
| templateVideoId | string | 是 | 底板视频素材文件 ID，使用文件上传接口接口上传视频文件获取文件ID，其中 providerType 参数填写：OPEN_CUSTOMIZATION_2D_EXCLUSIVE 视频要求： 1. 数量：1个 2. 大小：3GB以内 3. 时长：10秒 - 4分钟闭嘴视频 4. 格式：mp4（H.264编码）或 webm（vp8、vp9码） 5. 分辨率：1080p、2k、4k（2k、4k人像训练限时免费，只支持用于视频合成场景，不支持交互、直播等实时渲染推流场景） 6. 比例：16 : 9 或 9 : 16 7. 帧率：25 fps 8. 色彩标准：SDR-Rec.709（非HDR） 9. 视频素材里面需要带有相同长度的音频 2D小样本数字人（专属口型）拍摄指南 |
| lipVideoId | string | 是 | 唇动视频素材文件 ID，使用文件上传接口接口上传视频文件获取文件ID，其中 providerType 参数填写：OPEN_CUSTOMIZATION_2D_EXCLUSIVE 视频要求： 1. 数量：1个 2. 大小：3GB以内 3. 时长：4 - 8 分钟张嘴说话视频 4. 格式：mp4（H.264编码）或 webm（vp8、vp9码） 5. 帧率：25 fps 6. 色彩标准：SDR-Rec.709（非HDR） 7. 格式、分辨率、比例：必须与底板视频的参数保持一致 8. 视频素材里面需要带有相同长度的音频 2D小样本数字人（专属口型）拍摄指南 |
| maskVideoId | string | 否 | 底板视频对应的mask视频（人像遮罩视频）文件 ID，mask视频处理说明，使用文件上传接口接口上传视频文件获取文件ID，其中 providerType 参数填写：OPEN_CUSTOMIZATION_2D_EXCLUSIVE 若采用【透明背景类型数字人-方案二】，本参数必填。 视频要求： 1. 数量：1个 2. 大小：3GB以内 3. 格式：mp4（H.264编码） 4. 素材内容、时长、分辨率、帧率：必须与底板视频的参数保持一致 |
| callbackUrl | string | 否 | 接口调用方接受任务回调通知的url，规则和接口说明参考 接口通用说明，回调消息定义如下表。 |
回调参数
- type: FIGURE_2D_LITE_GENERATE
- data:
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| figureId | string | 是 | 人像ID |
| status | string | 是 | 状态： 1. GENERATING（开始训练） 2. SUCCESS（成功） 3. FAILED（失败） |
| failedCode | int | 否 | 失败错误码 |
| failedMessage | string | 否 | 失败错误信息 |
返回参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| figureId | string | 是 | 人像ID，用于调用人像查询接口查询人像状态 |
请求示例
{
"name": "数字人test-dong30",
"customizeType": "LITE_2D_GENERAL",
"gender": "MALE",
"keepBackground": false,
"templateVideoId": "30085e2d-b343-4b09-af25-a28430598230",
"maskVideoId": null,
"callbackUrl": "http://api-gateway:8080/api/digitalhuman/internal/api-gateway/v1/callback/vp/test"
}返回示例
{
"code": 0,
"message": {
"global": "success"
},
"result": {
"figureId": "2153"
},
"requestId": "b978a051-fafe-4623-bfa5-1c07566e88ac",
"success": true
}错误码
| 错误码 | 描述 |
|---|---|
| 10006 | 参数校验不通过 |
| 10011 | 没有购买形象定制的组件商品 |
| 21001 | 形象包训练任务提交异常 |
| 21002 | 找不到人像ID |
| 21003 | 人像查询异常 |
| 50001 | 额度预扣除失败 |
| 50002 | 余额不足 |
| 1002100000 | 情况1：透明背景，并且用的是方案一，那么有可能是webm视频没有带alpha通道 |
| 1004000000 | 情况1：透明背景，并且用的是方案二，那么有可能是底板视频和mask视频传反了，无法识别人脸 |
| 1006000000 | 情况1：透明背景，并且用的是方案二，那么有可能是底板视频和mask视频传反了，无法识别人脸 |
查询人像
接口说明
分页查询定制的数字人人像列表，接口鉴权和通用分页参数查阅：接口通用说明。
接口协议
GET /api/digitalhuman/open/v1/figure/lite2d/query
GET 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| figureId | string | 否 | 指定人像ID查询，为空则查询该账号下所有人像 |
| systemFigure | boolean | 否 | 是否查询平台的公共人像 1. 为空：查询全部 2. true：返回平台公共人像 3. false：返回定制人像 |
| trainSuccess | boolean | 否 | 是否查询训练完成，状态可用的人像 1. 为空：不进行过滤 2. true：只返回可用人像（平台公共人像+训练成功状态的定制人像） 3. false：只返回排队中、训练中或训练失败的定制人像 |
| pageNo | int | 否 | 页码，默认为1 |
| pageSize | int | 否 | 每页容量，默认10 |
返回参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| figureId | string | 是 | 人像ID |
| name | string | 是 | 数字人名称 |
| customizeType | string | 是 | 定制类型 |
| systemFigure | boolean | 是 | 是否是平台公共人像 |
| gender | string | 是 | 性别 |
| keepBackground | boolean | 是 | 是否保留底板视频背景 |
| taskSubmitTime | string | 是 | 任务提交时间 |
| templateImg | string | 是 | 数字人缩略图 |
| templateVideoUrl | string | 是 | 底板视频URL |
| resolutionWidth | int | 是 | 底板视频宽 |
| resolutionHeight | int | 是 | 底板视频高 |
| maskVideoUrl | string | 否 | mask视频URL |
| status | string | 是 | 状态 1. LINE_UP（排队中） 2. GENERATING（训练中） 3. SUCCESS（训练成功） 4. FAILED（训练失败） |
| failedCode | int | 否 | 失败错误码 |
| failedMessage | string | 否 | 制作失败原因 |
请求示例
GET /api/digitalhuman/open/v1/figure/lite2d/query?figureId=931返回示例
{
"code": 0,
"message": {
"global": "success"
},
"result": {
"pageNo": 1,
"pageSize": 9,
"totalCount": 1,
"result": [
{
"figureId": "931",
"name": "沐芸",
"customizeType": "LITE_2D_PERSONAL",
"systemFigure": true,
"gender": "FEMALE",
"keepBackground": true,
"templateVideoUrl": "https://digital-human-pipeline-output.cdn.bcebos.com/2023-06-09T07:21:17.334022/011+1.mp4",
"maskVideoUrl": null,
"resolutionWidth": 1080,
"resolutionHeight": 1920,
"status": "SUCCESS",
"templateImg": "http://star-light-lite.cdn.bcebos.com/2023-06-09T07:21:27.1936862023-06-09T07:21:27.193686.png",
"taskSubmitTime": "2035-12-29 23:57:00",
"failedCode": 0,
"failedMessage": null
}
]
},
"requestId": "ac0c9acd-69fa-40bd-aa37-f2463beb2f30",
"success": true
}