动作模仿 Motion Control

动作模仿用于让目标图片主体模仿参考视频中的动作。适合角色动作迁移、舞蹈/运动动作复刻、人物动态生成等场景。

接入流程

上传参考视频 -> 上传目标主体图片 -> 发起 Mimic 任务 -> 查询任务状态

接口地址

请求参数

参数	类型	是否必填	说明
`source_video_id`	integer	条件必填	PixVerse 生成的视频 ID；与 `video_media_id` 二选一
`video_media_id`	integer	条件必填	上传视频获得的 media ID；与 `source_video_id` 二选一
`img_id`	integer	是	上传目标主体图片后获得的图片 ID
`quality`	string	是	`360p`、`540p`、`720p`，不支持 `1080p`
`post_reference`	string	否	姿态参考类型：`image` 参考图片姿态；`video` 参考视频姿态。区分大小写；不传或空字符串采用下游默认行为
`webhook_id`	string	否	Webhook 配置 ID，必须是可解析的数字字符串，例如 `"345678"`

最小请求示例

{
  "video_media_id": 123456,
  "img_id": 987654,
  "quality": "540p"
}

指定姿态参考

字段名必须写作 post_reference，不是 pose_reference。

值	行为
`image`	参考图片姿态
`video`	参考视频姿态
不传或 `""`	采用下游默认行为，不应假定等同于 `image` 或 `video`

以下示例使用已上传视频，并指定参考图片姿态。示例 ID 需替换为当前账户的真实资源 ID；仅在已配置 Webhook 时传入对应数字字符串 ID。

{
  "img_id": 123456,
  "video_media_id": 234567,
  "quality": "720p",
  "post_reference": "image",
  "webhook_id": "345678"
}

若需参考视频姿态，将 post_reference 改为 "video"。该参数不改变图片必填、视频来源二选一和分辨率限制。

国内接口还可选传 water_mark、ai_watermark（当前支持 ai_gen）和 aigc_metadata。海外请求结构不包含这组水印参数。

参数组合与素材来源

规则	说明
视频来源	`source_video_id` 与 `video_media_id` 必须且只能填写一个。前者来自 PixVerse 视频生成结果，后者来自上传资源接口。
目标主体图片	本接口只使用单个 `img_id`，值来自 `POST /openapi/v2/image/upload` 的 `Resp.img_id`；不要填写 `img_ids`。
输出清晰度	`quality` 为必填字段，可选值为 `360p`、`540p`、`720p`。

响应字段

字段	类型	说明
`ErrCode`	integer	错误码，`0` 表示成功
`ErrMsg`	string	错误信息，成功时通常为 `Success`
`Resp.video_id`	integer	视频任务 ID，后续用于查询任务状态
`Resp.credits`	integer	创建响应返回的任务积分计算值，用于展示和初步对账；最终扣费以账户用量明细和任务最终状态为准

响应示例

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "video_id": 123456,
    "credits": 60
  }
}

参数错误示例

post_reference 为其他值或大小写不符（如 "Image"）时，返回 HTTP 400，业务码 400017：

{
  "ErrCode": 400017,
  "ErrMsg": "post_reference must be either \"image\" or \"video\""
}

下一步

调用「查询任务状态」接口，通过返回的 video_id 获取生成进度和最终视频 URL。

注意事项

参考视频负责动作，目标图片负责主体外观。

目标图片中主体越清晰，动作迁移效果越稳定。

如果参考视频动作复杂，建议先用较低分辨率验证效果。

动作模仿 Motion Control