文档中心

AI MediaKit

视频工具 API

提交深度动作捕捉任务 API

POST https://mediakit.cn-beijing.volces.com/api/v1/tools/video-depth

本 API 用于提交异步深度动作捕捉任务，逐帧估计视频画面的空间层次，弱化人物外观、服装、背景和画风信息，保留动作轮廓、空间位移和镜头运动，生成具有时间连续性的相对深度视频，适用于 AI 视频动作参考、角色替换与动作复刻、运镜控制、三维内容与视觉特效预处理。

说明

如需了解完整的使用流程和应用示例，请参阅深度动作捕捉。

请求参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	API 鉴权凭证，格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

参数	类型	是否必选	示例值	描述
video_url	String	是	https://example.com/dance_reference.mp4	待处理视频 URL。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。视频时长：单个视频时长不得超过 10 分钟. 视频内容：必须包含有效视频流，分辨率不得超过 2K。
model	String	否	standard	深度估计模型档位。仅支持 standard，默认值为 standard。该档位处理较快，适合效果预览和批量业务中的单视频处理。
client_token	String	否	video_depth_request_001	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	asset_id_20261021_001	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

请求示例

响应说明

接口会立即返回同步响应，表示任务是否成功进入处理队列。

响应参数

参数	类型	描述
success	Boolean	是否成功提交任务。
task_id	String	任务唯一标识。仅在 success 为 true 时返回有效值，用于查询任务状态和结果。
request_id	String	本次 API 请求的唯一标识，可用于问题排查。
error	Object	错误详情，仅在 success 为 false 时返回。

Error 对象

参数	类型	描述
code	String	错误码。请参阅错误码。
type	String	错误类型，例如 BadRequest。
message	String	错误详情。
param	String	导致错误的参数；仅在可定位具体参数时返回。

响应示例

成功响应

失败响应

异步任务结果

深度动作捕捉是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果：

方法一（轮询查询）：使用提交任务时获取的 task_id，定期调用查询任务信息 API，直到 status 字段变为 completed 或 failed。

方法二（事件回调）：在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 callback_url 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅事件回调。

当任务成功完成后，您获取到的任务信息中的 result 字段将包含以下内容。

参数	类型	示例值	描述
video_url	String	https://example.volcvideo.com/video-depth/result.mp4?auth_key=1777464650-example	HEVC 编码的相对深度视频下载地址，有效期为 24 小时。请及时下载并保存。
duration	Number	18.6	输出深度视频的总时长，单位为秒，用于用量计量。

任务完成后的完整响应示例：

最近更新时间：2026.10.27 11:59:57

这个页面对您有帮助吗？

有用

无用