本文为您详细介绍如何调用 StartExecution 接口提交异步的精细化字幕擦除任务，对指定音视频文件进行处理。该接口依托高精度的 OCR 和 AIGC 图像修复算法，支持全自动或手动框选消除视频中的内嵌字幕，最终输出无痕修复后的全新视频文件。

使用说明

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

接口行为与场景：本接口为异步接口，调用成功后仅代表任务提交成功并返回一个 RunId。系统将在后台异步执行字幕检测和擦除。核心参数与控制逻辑说明如下：

擦除模式 (Erase.Mode)：Auto（自动）模式依赖 OCR 算法对中英文的精准识别，能自动保护非字幕场景文字；若处理泰语、越南语等小语种，推荐切换为 Manual（手动）模式并配合 Locations（擦除框）进行强制区域擦除。

精细化控制 (EraseOption)：如果只想保留片头片尾的字幕，或仅擦除正片某一段的字幕，可通过此参数设置 Skip（跳过）或 Selected（选中）时间片段，避免一刀切的全片擦除。

成本与画质平衡 (VideoOption.EncodeMode)：默认 Quality（画质优先）会以高码率输出，文件体积会明显变大；若对分发带宽和存储成本敏感，强烈建议设置为 Size（大小优先），使输出码率向源视频靠拢。

结果获取方式：任务提交后，系统将在后台进行异步处理。您可以通过以下任一方式获取任务的最终结果：

主动查询：调用 GetExecution，传入 RunId 来轮询任务状态。若任务成功，可在返回的 Output.Task.Erase.File 中获取输出的 FileName 或新 Vid。

事件通知：配置事件通知并订阅媒体处理任务执行完成事件，任务完成后系统将主动向您配置的地址发送回调通知。

注意事项

计费说明：提交任务会产生视频 AI 费用，具体参见视频 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 必选示例值：Erase

任务类型：

Erase: 精细化字幕擦除任务。

Erase Object 可选示例值：-

精细化字幕擦除任务配置。当 Type 为 Erase 时需要设置此参数。

Mode String 必选示例值：Auto

字幕擦除模式，取值如下：

Auto：自动擦除模式。在此模式下，系统将启用 OCR 识别，并依据检测结果进行擦除操作。

Manual：(Beta) 手动擦除模式。在此模式下，系统不会启用 OCR 识别，仅擦除白色字幕内容。

说明

不同模式的用途及适用场景说明如下：

一般情况下，可将 Mode 设置为 Auto，再将 Auto.Type 设置为 Subtitle（仅字幕）或 Text（字幕和其它渲染文本），以擦除指定类型的文本。

若您对擦除区域有特殊需求，可通过设置 Locations 来指定擦除框，仅擦除框内经 OCR 识别的文本。

在需要擦除中英文外的小语种字幕的场景中，可将 Mode 设置为 Manual，并设置 Locations来指定擦除框。

Auto Object 可选示例值：-

自动擦除模式配置

Type String 必选示例值：Subtitle

文本擦除类型:

Subtitle: 擦除 OCR 检测为字幕的文本

Text: (Beta) 擦除除场景文字（如宫殿门牌匾等）以外的字幕及其他文本（如人物介绍等）。

Locations Object[] 可选示例值：-

擦除框数组。添加擦除框后，系统仅擦除框内文本。

RatioLocation Object 可选示例值：-

擦除框位置信息

说明

关于设置擦除框参数的详细介绍，请见提交字幕精细化擦除任务。

TopLeftX Double 可选示例值：0

框选区域左上角相对于视频左上角在X轴上的偏移比例，取值范围为[0,1]，其中 0 表示无偏移（与视频左边缘对齐），1 表示完全偏移（与视频右边缘对齐）。

TopLeftY Double 可选示例值：0

框选区域左上角相对于视频左上角在 Y 轴上的偏移比例，取值范围为 [0,1]，其中 0 表示无偏移（与视频上边缘对齐），1 表示完全偏移（与视频下边缘对齐）。

BottomRightX Double 可选示例值：0

框选区域右下角相对于视频左上角在 X 轴上的偏移比例，取值范围为 [0,1]，其中 0 表示无偏移（与视频左边缘对齐），1 表示完全偏移（与视频右边缘对齐）。

BottomRightY Double 可选示例值：0

框选区域右下角相对于视频左上角在 Y 轴上的偏移比例，取值范围为 [0,1]，其中 0 表示无偏移（与视频上边缘对齐），1 表示完全偏移（与视频下边缘对齐）。

SubtitleFilter Object 可选示例值：-

用于指定擦除文字的高度和距离视频宽度中心的比例，精确控制擦除范围。

注意

仅当 Mode 为 Auto、Type 为 Subtitle时生效。

MinTextHeightRatio Double 可选示例值：0.01

文字高度最小比例，默认值为 0.01，即视频高度的 1%。

MaxTextHeightRatio Double 可选示例值：0.1

文字高度最大比例，默认值为 0.1，即视频高度的 10%。

RectangleCenterOffsetRatio Double 可选示例值：0.1

文字区域中心偏离视频宽中心的比例。默认值为 0.08，即 8%。

Manual Object 可选示例值：-

手动擦除模式配置

Locations Object[] 可选示例值：-

擦除框数组。添加擦除框后，系统仅擦除框内文本。

RatioLocation Object 可选示例值：-

擦除框位置信息

说明

关于设置擦除框参数的详细介绍，请见提交字幕精细化擦除任务。

TopLeftX Double 可选示例值：0

框选区域左上角相对于视频左上角在X轴上的偏移比例，取值范围为[0,1]，其中 0 表示无偏移（与视频左边缘对齐），1 表示完全偏移（与视频右边缘对齐）。

TopLeftY Double 可选示例值：0

框选区域左上角相对于视频左上角在 Y 轴上的偏移比例，取值范围为 [0,1]，其中 0 表示无偏移（与视频上边缘对齐），1 表示完全偏移（与视频下边缘对齐）。

BottomRightX Double 可选示例值：0

框选区域右下角相对于视频左上角在 X 轴上的偏移比例，取值范围为 [0,1]，其中 0 表示无偏移（与视频左边缘对齐），1 表示完全偏移（与视频右边缘对齐）。

BottomRightY Double 可选示例值：0

框选区域右下角相对于视频左上角在 Y 轴上的偏移比例，取值范围为 [0,1]，其中 0 表示无偏移（与视频上边缘对齐），1 表示完全偏移（与视频下边缘对齐）。

WithEraseInfo Boolean 可选示例值：true

是否返回擦除信息详情

NewVid Boolean 可选示例值：true

是否为擦除后的视频生成一个新的 Vid。

EraseOption Object 可选示例值：-

擦除选项。可用于指定仅对视频的特定时间片段进行或跳过字幕擦除，实现更精细的控制。

ClipFilter Object 可选示例值：-

视频片段过滤器。用于定义一个或多个时间片段，并指定对这些片段执行的操作模式（擦除或跳过）。

Mode String 必选示例值：Skip

片段处理模式。决定了如何处理 Clips 数组中定义的时间片段。

Skip: 跳过模式。系统将擦除整个视频，但会跳过 Clips 数组中指定的片段区域，使其字幕保持原样。

Selected: 选中模式。系统将仅对 Clips 数组中指定的片段区域进行字幕擦除，视频的其他部分保持原样。

Clips Object[] 必选示例值：-

目标时间片段数组。

Start Double 必选示例值：10

片段的起始时间，单位为秒。

End Double 必选示例值：20

片段的结束时间，单位为秒。

VideoOption Object 可选示例值：-

视频编码配置，用于指定字幕擦除后生成视频的编码方式。

EncodeMode String 可选示例值：Size

编码模式，支持以下两种取值：

Quality（默认值）：画质优先模式。此模式下，系统会采用较高的目标码率进行编码，以确保高画质。这通常会导致输出文件的码率显著高于源文件，文件体积也相应增大。

Size：大小优先模式。在保证一定画质的前提下，使输出码率尽量向源视频码率对齐。

Control Object 可选示例值：-

任务控制配置。

ClientToken String 可选示例值：QqS3o5L4BLFCDxGZ&b

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

CallbackArgs String 可选示例值：Example

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

返回参数

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

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

媒体处理任务执行 ID。

示例 1：竖屏短剧全自动擦除

场景描述：最常用的场景。针对中英文字幕的竖屏短剧进行全自动识别擦除，同时开启“大小优先”编码，确保输出视频体积不暴增，并生成新 Vid 方便管理。

示例 2：小语种字幕指定区域擦除（手动模式）

场景描述：针对泰语、西语等小语种，或者自动识别效果不佳的情况。通过手动框选视频底部（垂直位置 0.8-1.0 范围）进行强制修复，无需 OCR 算法识别文字。

示例 3：仅对视频正片片段执行擦除（时间段控制）

场景描述：视频的片头和片尾没有字幕或包含重要版权信息，只想擦除第 10 秒到第 120 秒之间的剧情字幕。

错误码

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

服务端 SDK

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