形象定制-2D小样本数字人（升级版）
更新时间：2026-04-27
接口说明
- 调用形象定制任务接口，提交真人拍摄视频，返回人像ID
- 接收任务结束的回调通知，或使用人像ID
查询人像定制任务状态 - 将定制人像用于端渲染交互组件-2D小样本数字人（升级版）
接口调用域名：https://open.xiling.baidu.com
接口鉴权和通用字段说明请查阅：接口通用说明
调用本接口需要在平台购买 2D 小样本数字人（升级版）并绑定到应用，操作说明参考：平台操作指引
接口列表
提交形象定制任务
接口说明
创建数字人训练任务，返回人像ID
接口协议
POST /api/digitalhuman/open/v1/figure/sdk/2d_train
Header Content-Type: application/json;charset=utf-8
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 数字人名称 命名要求： 1. 账户内名称唯一 2. 仅可输入中文、字母、数字、中划线、下划线 3. 不超过20个字符 |
| customizeType | string | 是 | 定制类型，固定填：LITE_2D_SDK |
| gender | string | 是 | 性别 1. MALE（男） 2. FEMALE（女） |
| keepBackground | boolean | 是 | 是否保留底板视频背景 1. true：固定背景（保留原背景，后续驱动渲染不支持替换背景图） （1）【底板视频（templateVideoId）】【唇动视频（lipVideoId）】上传mp4格式的视频，【底板mask视频（maskVideoId）】无需上传 2. false：透明背景（后续驱动渲染支持替换任意背景图） （1）【底板视频（templateVideoId）】【唇动视频（lipVideoId）】【底板mask视频（maskVideoId）】均需上传mp4格式的视频 |
| templateVideoId | string | 是 | 底板视频素材文件 ID，使用文件上传接口上传视频文件获取文件ID，其中 providerType 参数填写：OPEN_CUSTOMIZATION_2D_SDK 视频要求： 1. 数量：1个 2. 大小：2GB以内 3. 时长：10秒 - 2分钟闭嘴视频 4. 格式：mp4（H.264编码） 5. 分辨率：1080p 6. 比例：9 : 16 7. 帧率：25 fps 8. 色彩标准：SDR-Rec.709（非HDR） 9. 视频素材里面需要带有相同长度的音频 2D小样本数字人（专属口型）拍摄指南 |
| lipVideoId | string | 是 | 唇动视频素材文件 ID，使用文件上传接口上传视频文件获取文件ID，其中 providerType 参数填写：OPEN_CUSTOMIZATION_2D_SDK 视频要求： 1. 数量：1个 2. 大小：5GB以内 3. 时长：3 - 4 分钟张嘴说话视频 4. 格式：mp4（H.264编码） 5. 帧率：25 fps 6. 色彩标准：SDR-Rec.709（非HDR） 7. 格式、分辨率、比例：必须与底板视频的参数保持一致 8. 视频素材里面需要带有相同长度的音频 2D小样本数字人（专属口型）拍摄指南 |
| maskVideoId | string | 否 | 底板视频对应的mask视频（人像遮罩视频）文件 ID，mask视频处理说明，使用文件上传接口上传视频文件获取文件ID，其中 providerType 参数填写：OPEN_CUSTOMIZATION_2D_SDK 视频要求： 1. 数量：1个 2. 大小：2GB以内 3. 格式：mp4（H.264编码） 4. 素材内容、分辨率、帧率、帧数：必须与底板视频的参数保持一致 |
| callbackUrl | string | 否 | 接口调用方接受任务回调通知的url，规则和接口说明参考 接口通用说明，回调消息定义如下表。 |
回调参数
- type: FIGURE_2D_LITE_SDK
- data:
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| figureId | string | 是 | 人像ID |
| status | string | 是 | 状态 1. WAIT（排队中） 2. GENERATING（开始训练） 3. SUCCESS（成功） 4. FAILED（失败） |
| failedCode | int | 否 | 失败错误码 |
| failedMessage | string | 否 | 失败错误信息 |
返回参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| figureId | string | 是 | 人像ID，用于调用人像查询接口查询人像状态 |
请求示例
Java
1{
2 "name": "数字人test-dong30",
3 "customizeType": "LITE_2D_SDK",
4 "gender": "MALE",
5 "keepBackground": false,
6 "templateVideoId": "30085e2d-b343-4b09-af25-a28430598230",
7 "lipVideoId": "30085e2d-b343-4b09-af25-a28430598231",
8 "maskVideoId": null,
9 "callbackUrl": "http://callbackurl/api/digitalhuman/internal/api-gateway/v1/callback/vp/test"
10}返回示例
JSON
1{
2 "code": 0,
3 "message": {
4 "global": "success"
5 },
6 "result": {
7 "figureId": "2153"
8 },
9 "requestId": "b978a051-fafe-4623-bfa5-1c07566e88ac",
10 "success": true
11}错误码
| 错误码 | 描述 |
|---|---|
| 10006 | 参数校验不通过 |
| 10011 | 没有购买形象定制的组件商品 |
| 21001 | 形象包训练任务提交异常 |
| 21002 | 找不到人像ID |
| 21003 | 人像查询异常 |
| 50001 | 额度预扣除失败 |
| 50002 | 余额不足 |
| 1004000000 | 无法识别人脸 |
| 1012000000 | 情况1：视频开头或结尾存在黑帧（一般由剪辑软件引入），请检查删掉，并重新定制 情况2：视频逐帧读取失败，请检查视频编码是否正常，并重新定制 情况3：人脸偏转角度较大，人脸丢失，请重新拍摄 情况4：底板视频和mask视频帧数不一致 |
| 其他 | 内部异常请联系客服 |
查询人像
接口说明
查询定制的数字人人像，接口鉴权和通用分页参数查阅：接口通用说明。
接口协议
POST /api/digitalhuman/open/v1/sdk/2d/figure
POST 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| figureId | string | 是 | 指定人像ID查询 |
返回参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| taskId | string | 是 | 任务ID |
| url | string | 否 | 人像加密包 |
| status | string | 是 | 状态 1. LINE_UP（排队中） 2. GENERATING（训练中） 3. SUCCESS（训练成功） 4. FAILED（训练失败） |
| code | int | 是 | 状态码，0成功，非0失败 |
| message | string | 是 | 状态消息 |
请求示例
Plain
1{
2 "figureId": "3568678"
3}返回示例
生成中
JSON
1{
2 "code": 0,
3 "message": {
4 "global": "success"
5 },
6 "result": {
7 "taskId": "fig-sdzttvmgj8c0dzcg",
8 "status": "GENERATING"
9 },
10 "requestId": "7dc31665-c545-4e4b-8e31-c82dcdabe694",
11 "success": true
12}成功
Plain Text
1{
2 "code": 0,
3 "message": {
4 "global": "success"
5 },
6 "result": {
7 "taskId": "fig-sdyv4jmrjh8mkwcu",
8 "url": "https://open-api-test.bj.bcebos.com/566e471519e94092937f481bdfcc4484/file/12345678-97c8-462e-bb4b-f2cd76a5a492/3568678.enc",
9 "status": "SUCCESS"
10 },
11 "requestId": "bb893ece-7fbc-4a6f-b535-53dcc299ef97",
12 "success": true
13}评价此篇文章