POST https://mediakit.cn-beijing.volces.com/api/v1/tools/erase-video-subtitle-pro

本 API 用于提交一个异步的字幕擦除（精细化版）任务，针对视频中的字幕实现高质量的无痕擦除，最大程度地还原视频画面。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
video_url	String	是	https://example.com/video.mp4	待擦除字幕的视频 URL。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。输入分辨率限制：最高支持 2K 分辨率。输出分辨率：最高支持 1080P。
model_version	String	否	v4	擦除算法版本，默认值为 v4。 v4：（默认）V4 版擦除算法。 v5：V5 版擦除算法。相比 V4，V5 优化 AIGC 生成视频擦除字幕后的闪烁问题与带阴影字幕的擦除效果，优化误擦问题，并提升处理速度。 v5.6：V5.6 版擦除算法。在 V5 的基础上有效缓解擦除后的闪烁、水波纹问题，并新增对西班牙语、韩语、泰语、印尼语、越南语、日语、葡萄牙语、德语、法语等多语种字幕的擦除支持；但处理耗时较 v5 明显增加（与 v4 相当），且在动画文字、复杂背景等场景下仍可能出现漏擦或擦除不彻底的情况。
mode	String	否	Subtitle	字幕擦除模式，默认值为 Subtitle。 Subtitle：擦除 OCR 检测为字幕的文本。默认情况下，此模式仅处理视频画面下半部分（下方 50%）区域的字幕。如果同时配置了 erase_ratio_location 参数自定义擦除框，系统将只擦除自定义擦除框与画面下半部分区域的交集内的文本。 Text：擦除 OCR 检测为字幕及其他类型的文本（如人名、地名等），不包含场景文字（如牌匾）。此模式会对整个视频画面进行文本检测。如果同时配置了 erase_ratio_location 参数，系统将仅在指定的擦除框内执行擦除操作。
output_encode_mode	String	否	Quality	输出视频编码模式，默认值为 Quality。 Quality：画质优先模式。采用较高码率编码，画质更好，但文件体积可能更大。 Size：大小优先模式。在保证一定画质的前提下，使输出码率接近源文件。
erase_ratio_location	Array	否	[{"top_...}, {"top_...}]	全局擦除框位置数组列表。配置此参数后，系统将结合 mode 参数的设置，在指定的矩形框选区域内执行文本擦除。最多支持 20 个擦除框。详细结构见下文 Location 对象。注意此参数的行为会与 mode 参数联动。在 Subtitle 模式下，实际生效的擦除区域是自定义擦除框与画面下半部分的交集。此参数（全局擦除框）与 time_segment_filter.segments[].erase_ratio_location（分时间段独立擦除框）互斥，不能在同一次请求中配置。如需为不同时间段设置不同擦除区域，请改用分时间段擦除框。
time_segment_filter	Object	否	{"mode": "selected", ...}	擦除时间段控制。配置后按 mode 对指定时间段执行或跳过擦除；不配置则对整段视频生效。适用于只需擦除正片、保留片头/片尾字幕等场景。详细结构见下文 Time segment filter 对象。
subtitle_filter	Object	否	{"max_text_height_ratio": 0.1}	字幕特征过滤，用于更精确地判定哪些文本属于字幕。仅在 mode 为 Subtitle 时生效，不传则使用系统默认值。详细结构见下文 Subtitle filter 对象。
media_output_destination	String	否	vod://my-space	指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶。存储至 VOD：设为 vod://<您的空间名> 存储至 TOS：设为 tos://<您的桶名> 设置本参数后，任务结果中的 url 相关字段将返回形如 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。说明首次使用此功能前，您需要先授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。请前往 AI MediaKit 控制台基础配置 > 授权管理页面，根据您的需要，为 AI MediaKit 服务授予相应的权限。更多信息，请参阅开发指南处理产物存储至 VOD 或 TOS。
client_token	String	否	your_unique_request_id_136	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_custom_callback_args	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考按项目或 API Key 分账。

Location 对象

location 对象用于定义一个矩形擦除框，使用归一化的坐标系，以视频画面左上角为原点 (0, 0)、右下角为 (1, 1)，通过指定左上和右下两个顶点的坐标来确定擦除区域。

参数	类型	是否必选	示例值	描述
top_left_x	Number	是	0.1	框选区域左上角相对于视频左上角在 X 轴上的偏移比例。取值范围为 [0,1]。其中 0 表示无偏移（与视频左边缘对齐），1 表示完全偏移（与视频右边缘对齐）。
top_left_y	Number	是	0.8	框选区域左上角相对于视频左上角在 Y 轴上的偏移比例。取值范围为 [0,1]，其中 0 表示无偏移（与视频上边缘对齐），1 表示完全偏移（与视频下边缘对齐）。
bottom_right_x	Number	是	0.9	框选区域右下角相对于视频左上角在 X 轴上的偏移比例，取值范围为 [0,1]，其中 0 表示无偏移（与视频左边缘对齐），1 表示完全偏移（与视频右边缘对齐）。
bottom_right_y	Number	是	0.95	框选区域右下角相对于视频左上角在 Y 轴上的偏移比例，取值范围为 [0,1]，其中 0 表示无偏移（与视频上边缘对齐），1 表示完全偏移（与视频下边缘对齐）。

下图中的橙色虚线框即为擦除区域，对应以下 location 参数设置：

Time segment filter 对象

time_segment_filter 对象用于按时间维度控制擦除范围：只擦（或只跳过）视频中若干指定的时间段，常用于只处理正片、保留片头/片尾字幕等场景。

参数	类型	是否必选	示例值	描述
mode	String	是	selected	时间段处理模式。 skip：跳过 segments 中列出的时间段，对其余部分执行擦除。 selected：仅对 segments 中列出的时间段执行擦除。此模式下，还可为每个时间段单独指定擦除区域，实现“不同时间段擦除不同位置”的精细化控制。
segments	Array	是	[{"start_time": 10, "end_time": 60}]	时间段列表，至少包含 1 个时间段。每个元素结构见下文 Segment 对象。

Segment 对象

参数	类型	是否必选	示例值	描述
start_time	Number	是	10	片段起始时间，单位为秒，取值需大于等于 0。
end_time	Number	是	60	片段结束时间，单位为秒，取值需大于 start_time。
erase_ratio_location	Array	否	[{"top_...}]	该时间段专属的擦除框列表，用于为不同时间段指定各自独立的擦除区域，每个时间段最多支持 20 个擦除框，结构见 Location 对象。使用说明：仅在 time_segment_filter.mode 为 selected 时支持。分时间段与全局擦除框互斥，请择一使用。此参数不能与顶层的 erase_ratio_location 参数同时配置。若要对所有选定时间段应用相同的擦除框，建议使用顶层的 erase_ratio_location 参数。若要对不同时间段应用不同的擦除框，或对部分时间段应用擦除框、另一部分使用默认行为，请仅配置此分段参数。对于希望使用默认擦除行为的时间段，可将此字段设为空数组 [] 或不传。

Subtitle filter 对象

subtitle_filter 对象通过“文字高度”和“水平居中程度”的阈值，帮助系统更精确地识别字幕，以避免误擦标题、台标等非字幕内容。

参数	类型	是否必选	示例值	描述
min_text_height_ratio	Number	否	0.01	文字高度最小比例（相对视频高度），取值范围为 [0,1]。默认值为 0.01（即 1%）。低于此高度的文本不会被判定为字幕。
max_text_height_ratio	Number	否	0.1	文字高度最大比例（相对视频高度），取值范围为 [0,1]。高于此高度的文本不会被判定为字幕。不传时的默认值与 model_version 有关： v4：默认 0.2（即 20%）。 v5/v5.6：默认 0.1（即 10%）。
center_offset_ratio	Number	否	0.08	文字区域中心相对视频宽度中心的最大偏离比例，取值范围为 [0,1]。默认值为 0.08。超过此偏离比例的文本不会被判定为字幕。

下图说明了系统如何根据这些阈值判断文本是否为字幕。只有同时满足所有条件的文本（文本高度不低于下限、不高于上限，且水平方向足够居中）才会被擦除。对应如下 subtitle_filter 设置：

请求示例

以下示例演示了如何通过指定擦除框，对视频底部特定区域的文本进行擦除。

响应说明

调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。

响应参数

参数	类型	描述
success	Boolean	任务是否成功提交。 true：任务已成功提交到后台处理队列。 false：请求存在错误，任务提交失败。请检查 error 字段以获取详细信息。
task_id	String	任务的唯一标识符。仅在 success 为 true 时返回有效值。您可以使用此 ID 来查询任务状态和结果。
request_id	String	本次 API 请求的唯一标识符，可用于问题排查。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。

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/output.mp4?auth_key=...	擦除字幕后的视频文件地址。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
duration	Number	180.5	输出视频的总时长（单位：秒）。

最终的完整任务信息示例：

AI MediaKit