文档中心

视频点播

StartExecution - 提交媒体处理任务

提交智能抠图任务

本文为您详细介绍如何调用 StartExecution 接口提交异步的智能抠图任务，基于 AI 人像分割技术，可实现人像抠图和绿幕抠图，生成带 Alpha 透明通道或指定背景色的视频素材，适用于视频合成、虚拟背景替换等多种创意场景。

注意事项

开通白名单：智能抠图为白名单功能。使用前请提交工单联系火山引擎技术支持团队申请开通。

调用准备：在调用本接口前，建议您先阅读如何调用 OpenAPI 文档，以了解 OpenAPI 的通用调用流程，包括在线调试、获取 curl 命令、请求签名等基础操作。

计费说明：提交任务会产生视频 AI 费用，具体参见智能抠图计费说明。

QPS 限制：本接口的单用户 QPS 限制为 50 次/秒。超过限制，API 调用会被限流，这可能会影响您的业务，请合理调用。更多信息，请参见 QPS 限制。

请求说明

请求方式：POST

请求地址：https://vod.volcengineapi.com?Action=StartExecution&Version=2025-01-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

Query

Action String 必选示例值：StartExecution

接口名称。当前 API 的名称为 StartExecution。

Version String 必选示例值：2025-01-01

接口版本。当前 API 的版本为 2025-01-01。

Body

Input Object 可选示例值：-

输入文件信息。

Type String 必选示例值：Vid

输入文件类型。取值如下：

Vid：Vid 模式。此模式下，您还需设置 Vid 参数。

DirectUrl：DirectUrl 模式。此模式下，您还需设置 DirectUrl 参数。

Vid String 可选示例值：v0ccfeg7007acsg***fog65ubr7niqng

待处理视频的 Vid。您需要在调用本接口前，通过任一方式将视频上传至点播空间，并获取其 Vid。

注意

您必须设置 Vid 或 DirectUrl参数之一，但不能同时设置这两个参数。

DirectUrl Object 可选示例值：-

通过 DirectUrl 模式指定待处理视频的信息。您需要在调用本接口前，通过任一方式将视频上传至点播空间，并获取其相关信息。

注意

您必须设置 Vid 或 DirectUrl参数之一，但不能同时设置这两个参数。

SpaceName String 必选示例值：test

空间名称。可调用 ListSpace 获取当前账号下所有空间的信息。

FileName String 必选示例值：example.mp4

文件路径。音视频上传至视频点播服务后，您可通过媒资上传完成事件获取 FileName。

BucketName String 可选示例值：tos-cn-v-cd3a11

存储桶名称。可调用 ListSpace 获取空间所绑定的存储桶名称。

Operation Object 必选示例值：-

媒体处理操作配置。

Type String 必选示例值：Task

处理类型。取值如下：

Task：单任务。

Task Object 可选示例值：-

单任务配置。当 Type 为 Task 时需要设置此参数。

Type String 必选示例值：VideoMatting

任务类型：

VideoMatting：智能抠图任务。

VideoMatting Object 可选示例值：-

智能抠图任务配置。当 Type 为 VideoMatting 时需要设置此参数。

Model String 必选示例值：Human

抠图模型，支持的取值如下：

Human：人像抠图。可从复杂场景中识别人像主体并将其抠出，适用于背景替换等场景。

GreenScreen：绿幕抠图。专门用于处理在绿幕前拍摄的视频。

VideoOption Object 可选示例值：-

视频生成配置。用于指定抠图后输出视频的封装格式和背景颜色等参数。如不传 VideoOption，则默认生成 WEBM 格式视频。

Format String 必选示例值：WEBM

输出视频的封装格式，支持的取值如下：

WEBM

BackgroundColor String 可选示例值：#00FF00

输出视频的背景颜色，取值为 16 进制 RGB 颜色值。仅当 Format 为 MP4 时生效；当 Format 为 MOV 或 WEBM 时传入该参数会报错。未传入时默认为黑色（#000000）。

NewVid Boolean 可选示例值：true

是否生成新的 Vid：

true：为抠图后生成的视频分配一个新的 Vid。

false：（默认）不生成新的 Vid。

说明

当 Format 为 MOV 或 WEBM 时，输出透明底视频。

当 Format 为 MP4 时，输出指定背景色的纯色背景视频。

输出视频分辨率与原视频保持一致。原视频帧率不超过 30 fps 时，输出帧率跟随原视频；原视频帧率超过 30 fps 时，输出帧率为 30 fps。

Control Object 可选示例值：-

任务控制配置。

ClientToken String 可选示例值：QqS3o5L4BLFCDxGZ&b

用户请求凭证，用于区分不同请求。大小写敏感，不超过 64 个 ASCII 码可打印字符。默认情况下，视频点播转码服务在接收到触发工作流请求后，会执行幂等行为。这意味着，如果判定当前请求与之前发送的请求相同，则不会重复执行该请求。关于幂等行为、目的和条件，请参考工作流幂等说明。若您希望跳过幂等行为，例如修改了某一工作流所绑定的媒体处理模板中的配置，想要对同一个 Vid 重新执行相同的工作流，则可以设置此参数。

CallbackArgs String 可选示例值：Example

自定义字段，将在媒体处理任务执行完成事件中透传返回。字段长度最大为 512 字节。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

RunId String 示例值：hb:c5cacd4946bd***a5fd9f74159b03ae8

媒体处理任务执行 ID。

请求示例

通过 Vid 提交人像抠图任务。

错误码

本接口无特有的错误码。更多信息请见公共错误码。

服务端 SDK

视频点播为 OpenAPI 提供了配套的服务端 SDK，支持多种编程语言，帮助您实现快速开发。建议使用服务端 SDK 来调用 API。本接口仅 VOD SDK 2.0 支持，详见 V2.0 SDK 介绍与迁移说明。

最近更新时间：2026.08.06 15:10:02

这个页面对您有帮助吗？

有用

无用