照片数字人形象包定制接口
1 使用说明
1.1 使用流程
1、形象定制：本文档为照片数字人形象定制接口文档，服务端调用数字人开放平台“形象定制-照片数字人”接口，上传人像照片获取形象包文件。已生成形象包需要通过SDK驱动使用，不可单独使用。
2、SDK调用：客户端或页面集成端渲染交互组件-照片数字人SDK加载形象包，本地驱动渲染数字人。支持音频和文本驱动。音频可以使用真人音频或自行接入的第三方TTS的音频。文本驱动时 SDK 内部会调用数字人开放平台 TTS 服务驱动数字人。
1.2 照片要求
注意：输入的照片需符合以下规范，否则形象包渲染效果可能异常
- 图片格式：png，jpg
- 分辨率：分辨率不超过1080*1920px（建议人脸区域不超过256*256px）
- 照片要求：
1、照片清晰，光线自然。
2、人脸无遮挡、五官无遮挡。
3、直面镜头，人脸各方向转角控制在15°以内，不能出现侧脸、歪头、低头、仰头等情况。
4、不露牙齿，人脸表情尽量放松，避免抿嘴、张嘴等情况，允许小幅度微笑。
5、避免人物头部穿戴复杂头饰、帽子。
6、避免出现丸子头、马尾等高颅顶发型。
7、避免人物头发过于蓬松。
8、避免使用动漫人物等单线条唇形，需保证人物图片具备正常的真人唇型，否则无法保证效果。
1.3 购买入口：
组件商店：https://xiling.cloud.baidu.com/open/widgetStore/list
2 接口说明
接口调用地址：https://open.xiling.baidu.com 使用图片训练人像包
- 调用人像包训练接口，提交图片，返回任务ID
- 调用人像包查询接口，提交任务ID，获取训练信息，包含状态及人像包地址等
接口鉴权和通用字段说明请查阅：接口通用说明
3 接口列表
3.1 提交人像训练接口
3.1.1 接口说明
调用人像包训练接口，提交图片，返回任务ID
3.1.2 接口协议
POST /api/digitalhuman/open/v1/figure/image/create
Header Content-Type: application/json;charset=utf-8
3.1.3 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| figureImageUrl | string | 是 | 人像图片 url，url 字符长度不超过 1000，图片需要包含清晰的人脸，图片格式要求： 文件大小不超过 1.5 MB； 支持的图片格式：png、jpg、jpeg；当图片是包含透明通道的 png 格式，会返回 webm 格式透明背景视频，其他情况返回 mp4 格式视频。 |
| callbackUrl | string | 否 | 接口调用方接受任务回调通知的url，规则和接口说明参考 |
3.1.4 回调参数
- type: PICTURE_FIGURE_ADD
- data:
-
参数名 类型 是否必填 描述 taskId string 是 任务ID status string 是 状态： failedCode int 否 失败错误码 failedMessage string 否 失败错误信息1. SUCCESS（合成成功）2. FAILED（合成失败） figureUrl string 否 形象包文件地址，文件会保存 7 天
3.1.5 返回参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| taskId | string | 是 | 任务ID，用于调用任务查询接口查询任务状态 |
3.1.6 请求示例
1{
2 "requestId": "xxxx11",
3 "figureImageUrl": "https://meta-human-editor-prd.cdn.bcebos.com/ca1d70b6f73d44bebd2aba1f3deb60bb/draftThumbnail/dt-qfdkzu6nhawzayqb5.png",
4 "callbackUrl": "http://api-gateway:8080/api/digitalhuman/internal/api-gateway/v1/callback/vp/test"
5}3.1.7 返回示例
1{
2 "code": 0,
3 "message": {
4 "global": "success"
5 },
6 "result": {
7 "taskId": "fig-qgti819vzahqxpb3",
8 },
9 "requestId": "xxxx11",
10 "success": true
11}3.1.8 错误码
| 错误码 | 描述 |
|---|---|
| 0 | 正常返回 |
| 4911 | 找不到app信息，请确认appId是否输入正确 |
| 4913 | 无法访问API，可能是app没有绑定对应的组件，或url输入错误，或访问的人像不可用 |
| 10001 | 签名校验失败 |
| 10002 | 签名信息为空 |
| 10003 | 签名格式错误 |
| 10004 | 未识别错误的通用错误码 |
| 10005 | 请求体JSON解析失败，请确认是否是合法的JSON格式 |
| 10006 | 参数校验不通过 |
| 10011 | 没有购买对应的商品 |
| 14001 | 内部服务异常，请稍后再试 |
| 14002 | 内部服务异常，网络拥堵 |
| 20001 | 未检查到人脸 |
| 20034 | 图片下载异常 |
| 21001 | 形象包任务提交失败 |
3.2 查询任务
3.2.1 接口说明
使用任务ID查询任务状态
3.2.2 接口协议
GET /api/digitalhuman/open/v1/figure/image/task
3.2.3 GET 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| taskId | string | 是 | 任务ID |
3.2.4 返回参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| taskId | string | 是 | 任务ID |
| status | string | 是 | 状态： |
| failedCode | int | 否 | 失败错误码1. SUBMIT（已提交待合成）2. GENERATING（合成中）3. SUCCESS（合成成功）4. FAILED（合成失败） |
| failedMessage | string | 否 | 失败错误信息 |
| figureUrl | string | 否 | 形象包文件地址，文件会保存 7 天 |
| createTime | string | 是 | 创建时间，示例：2024-04-29T20:28:06 |
| updateTime | string | 是 | 更新时间，示例：2024-04-29T20:28:06 |
3.2.5 请求示例
1GET /api/digitalhuman/open/v1/figure/image/task?taskId=abc123&requestId=123e4567-e89b-12d3-a456-4266141740003.2.6 返回示例
1{
2 "code": 0,
3 "message": {
4 "global": "success"
5 },
6 "result": {
7 "taskId": "fig-qgti819vzahqxpb3",
8 "status": "GENERATING",
9 "failedCode": 0,
10 "failedMessage": "",
11 "figureUrl": null,
12 "createTime": "2024-07-18T08:17:56",
13 "updateTime": "2024-07-18T08:17:56"
14 },
15 "requestId": "fdc66116-762d-4a82-a082-e83357a3167e",
16 "success": true
17}3.3 提交照片抠图接口
3.3.1 接口说明
调用照片抠图接口，提交图片，返回抠图结果
3.3.2 接口协议
POST /api/digitalhuman/open/v1/photo/bodyseg
Header Content-Type: application/json;charset=utf-8
3.3.3 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| imgUrl | string | 是 | 人像图片文件url，必须为 BOS 文件地址（通过 https://cloud.baidu.com/product/bos.html 上传后获得） 图片需要包含清晰的人脸，图片格式要求： 1. 文件大小不超过 3 MB 2. 支持的图片格式：png、jpg、jpeg； 3. 图片分辨率不超过1080P 图片内容要求： 1. 照片清晰，只有单个人脸 2. 面部正对镜头，轮廓完整 3. 面部无明显阴影，无头发遮挡 |
| customizeType | string | 是 | 定制类型: OPEN_PHOTO_KEYING（照片抠像） |
3.3.4 返回参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| imgResultUrl | string | 是 | 抠图结果。文件保存 7 天，请及时使用 |
3.3.5 请求示例
1{
2 "requestId": "xxxxx1",
3 "imgUrl": "xxxxxx",
4 "customizeType": "OPEN_PHOTO_KEYING"
5}3.3.6 返回示例
1{
2 "code": 0,
3 "message": {
4 "global": "success"
5 },
6 "result": {
7 "imgResultUrl": "https://meta-human-editor-prd.cdn.bcebos.com/ca1d70b6f73d44bebd2aba1f3deb60bb/draftThumbnail/dt-qfdkzu6nhawzayqb5.png"
8 },
9 "requestId": "xxxx11",
10 "success": true
11}3.3.7 错误码
| 错误码 | 描述 |
|---|---|
| 10006 | 参数校验不通过 |
| 10011 | 没有购买对应的商品 |
| 25001 | 图片抠像失败 |
| 25003 | 图片格式不正确，请检查 |
| 25004 | 图片大小过大，请检查 |
| 25005 | 图片分辨率过大，请检查 |
| 25006 | 图片解析错误，请检查 |
| 25007 | 图片地址必须为BOS文件地址，请检查 |
| 25008 | 图片下载失败，请检查图片是否存在 |