2D小样本数字人抠像接口
更新时间:2024-12-31
接口说明
接口调用地址:https://open.xiling.baidu.com
抠像接口支持对用户上传的视频进行背景扣除处理。该接口能够智能识别并保留视频中的人像,无论是实景视频还是绿幕拍摄,都可以实现高效、精准的背景去除。适用于需要背景替换或去除的各种应用场景。
本功能需要应用绑定「形象定制-2D小样本数字人(通用口型)」或者「形象定制-2D小样本数字人(专属口型)」组件才能使用。
拍摄指南参考:https://cloud.baidu.com/doc/AI_DH/s/8m0uiiv0m
接口鉴权和通用字段说明请查阅:接口通用说明
接口列表
抠像任务
接口说明
提供视频背景抠像功能,提交任务,返回抠像处理后的视频URL及视频ID,视频ID可直接用于2D小样本形象定制。
接口协议
POST /api/digitalhuman/open/v1/figure/lite2d/background/submit
Header Content-Type: application/json;charset=utf-8
请求参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
videoId | string | 是 | 视频素材文件 ID,视频素材不允许包含黑帧,否则人像训练会导致帧数不匹配报错,使用文件上传接口接口上传视频文件获取文件ID,其中providerType 参数填写: 通用口型人像:OPEN_CUSTOMIZATION_2D_GENERAL 专属口型人像:OPEN_CUSTOMIZATION_2D_EXCLUSIVE 视频要求: 1. 数量:1个 2. 大小:3GB以内 3. 时长:10秒-8分钟以内 4. 格式:mp4(H.264编码) 5. 分辨率:1080p、2k、4k 6. 比例:16:9或9:16 7. 帧率:25 fps 8. 色彩标准:SDR-Rec.709(非HDR) |
type | string | 是 | 视频类型: 1. GREEN:表示绿幕背景,抠图时去掉绿幕,保留前景; 2. REAL:表示实景视频,抠图只能保留人像。 |
callbackUrl | string | 否 | 接口调用方接受任务回调通知的url,规则和接口说明参考 接口通用说明,回调消息定义如下表。 |
回调参数
- type: FIGURE_2D_LITE_BACKGROUND
- data:
参数名 | 类型 | 是否必填 | 描述 |
---|---|---|---|
taskId | string | 是 | 任务ID |
status | string | 是 | 状态: 1. LINE_UP (排队中 ) 2. GENERATING(抠像中) 3. SUCCESS(成功) 4. FAILED(失败) |
videoMaskId | string | 否 | 抠像后的视频MaskID,在人像训练接口使用(省去视频上传的步骤),当status=SUCCESS时会有值。 |
videoUrl | string | 否 | 抠像后的视频url(仅用来查看效果),当status=SUCCESS时会有值。 |
failedCode | int | 否 | 失败错误码 |
failedMessage | string | 否 | 失败错误信息 |
返回参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
taskId | string | 是 | 任务ID,用于调用人像查询接口查询抠像任务状态 |
请求示例
Plain
1{
2 "videoId": "cddbadc3-47ad-4bc3-bb0e-be58c8e4c681",
3 "type": "REAL",
4 "callbackUrl": "http://api-gateway:8080/api/digitalhuman/internal/api-gateway/v1/callback/vp/test"
5}
返回示例
Plain
1{
2 "code": 0,
3 "message": {
4 "global": "success"
5 },
6 "result": {
7 "taskId": "bkg-qmur7u3her5cn255"
8 },
9 "requestId": "d1f10c73-f43d-4933-ad9f-4cd20df5da55",
10 "success": true
11}
错误码
错误码 | 描述 |
---|---|
0 | 正常返回 |
4911 | 找不到app信息,请确认appId是否输入正确 |
4913 | 无法访问API,可能是app没有绑定对应的组件,或url输入错误,或访问的人像不可用 |
10001 | 签名校验失败 |
10002 | 签名信息为空 |
10003 | 签名格式错误 |
10004 | 未识别错误的通用错误码 |
10005 | 请求体JSON解析失败,请确认是否是合法的JSON格式 |
10006 | 参数校验不通过 |
10011 | 没有购买对应的商品 |
21007 | 【视频素材】该文件不是您的,请检查 |
30009 | 获取【视频素材】异常:查询的fileId不存在 |
150011 | 抠图任务提交失败 ,请稍后再试 |
150012 | 抠图任务训练失败 ,请稍后再试 |
其他错误码 | 内部服务异常,请稍后再试或联系客服处理 |
查询任务
接口说明
使用任务ID查询任务状态
接口协议
GET /api/digitalhuman/open/v1/figure/lite2d/background/task
GET 请求参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
taskId | string | 否 | 为空则查询该账号下所有任务ID |
pageNo | int | 否 | 页码,默认为1 |
pageSize | int | 否 | 每页容量,默认10 |
返回参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
taskId | string | 是 | 任务ID |
status | string | 是 | 状态: 1. LINE_UP (排队中 ) 2. GENERATING(抠像中) 3. SUCCESS(成功) 4. FAILED(失败) |
videoMaskId | string | 否 | 抠像后的视频MaskID,在人像训练接口使用(省去视频上传的步骤),当status=SUCCESS时会有值。 |
videoUrl | string | 否 | 抠像后的视频url(仅用来查看效果),当status=SUCCESS时会有值。 |
type | string | 是 | 视频类型 1. GREEN,表示绿幕背景,抠图时去掉绿幕,保留前景; 2. REAL,表示实景视频,抠图只能保留人像。 |
failedCode | int | 否 | 失败错误码 |
failedMessage | string | 否 | 失败错误信息 |
createTime | string | 是 | 创建时间,示例:2024-04-29T20:28:06 |
updateTime | string | 是 | 更新时间,示例:2024-04-29T20:28:06 |
请求示例
Plain
1GET /api/digitalhuman/open/v1/figure/lite2d/background/task?taskId=bkg-qmur7u3her5cn255
返回示例
Plain
1{
2 "code": 0,
3 "message": {
4 "global": "success"
5 },
6 "result": {
7 "pageNo": 1,
8 "pageSize": 10,
9 "totalCount": 16,
10 "result": [
11 {
12 "taskId": "bkg-qm0vj6dmkdah047w",
13 "status": "SUCCESS",
14 "videoMaskId": "21ca0c1c-338a-472c-8ce4-79c84ceb4f30",
15 "videoUrl": "http://bridge.bj.bcebos.com/2d_train_server_open_sanbox/bkg-qm0vj6dmkdah047w_/work/workdir/bkg-qm0vj6dmkdah047w/results/3ec90927-9ab4-4a9a-a993-7e8f382dcdde_fusion.mp4?authorization=bce-auth-v1%2Fa0208a0779694c2fbefe77194d71db41%2F2024-12-25T11%3A42%3A46Z%2F-1%2F%2F691e70579efa0d5996108729dbf855d96279e1af9fa9ec5dbc02d22e656b2bc0",
16 "type": "REAL",
17 "failedCode": 0,
18 "createTime": "2024-12-25 19:40:20",
19 "updateTime": "2024-12-25 19:42:46"
20 }
21 ]
22 },
23 "requestId": "fc7b4d7f-6d38-404b-a1c9-ff89fffe5c1f",
24 "success": true
25}