# 字幕擦除

> 精细擦除视频画面中的硬字幕与文字，支持指定擦除区域、时间窗与字幕高度过滤。兼容火山云 AI MediaKit 官方格式。

字幕擦除自动识别并擦除视频画面中**烧录在画面上的硬字幕、文字**，还原干净画面，支持精细控制：限定擦除区域、只处理指定时间段、按文字高度过滤，常用于素材二次创作、多语言重制、去水印等场景。

```
POST /api/aimediakit/api/v1/tools/erase-video-subtitle-pro
```

## 请求体

| 字段 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `video_url` | string | 是 | — | 源视频公网链接（`http(s)`，最长 1024 字符） |
| `model_version` | string | 否 | `v4` | 模型版本，可选 `v4` / `v5` |
| `mode` | string | 否 | `subtitle` | 擦除模式：`subtitle`（字幕）/ `text`（画面文字） |
| `output_encode_mode` | string | 否 | `quality` | 输出编码取向：`quality`（画质优先）/ `size`（体积优先） |
| `erase_ratio_location` | array | 否 | — | 擦除区域列表（归一化矩形），不传则全画面自动识别，见下 |
| `time_segment_filter` | object | 否 | 全片 | 时间窗过滤，见下 |
| `subtitle_filter` | object | 否 | — | 字幕高度 / 位置过滤，见下 |

### `erase_ratio_location[]` 元素

坐标为 **0..1 归一化**比例（相对画面宽高），`bottom_right` 必须严格大于 `top_left`：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `top_left_x` | number | 矩形左上角 x（0..1） |
| `top_left_y` | number | 矩形左上角 y（0..1） |
| `bottom_right_x` | number | 矩形右下角 x（0..1） |
| `bottom_right_y` | number | 矩形右下角 y（0..1） |

### `time_segment_filter`

| 字段 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `mode` | string | `all` | `all`（全片处理）/ `selected`（仅处理选中时间段）/ `skip`（跳过选中时间段）。`selected` 时 `segments` 必填且非空 |
| `segments` | array | — | 时间窗数组，元素为 `{start_time, end_time}`（单位：秒，要求 `end_time` 大于 `start_time`） |

### `subtitle_filter`

均为可选，缺省不过滤：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `min_text_height_ratio` | number | 最小文字高度占比，低于此高度的文字不擦除 |
| `max_text_height_ratio` | number | 最大文字高度占比，高于此高度的文字不擦除 |
| `center_offset_ratio` | number | 相对画面中心的偏移占比过滤 |

## 示例

<CodeGroup>

```bash cURL
curl -X POST "https://api.looprouter.com/api/aimediakit/api/v1/tools/erase-video-subtitle-pro" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "video_url": "https://example.com/source.mp4",
    "model_version": "v4",
    "mode": "subtitle",
    "output_encode_mode": "quality",
    "erase_ratio_location": [
      { "top_left_x": 0.1, "top_left_y": 0.82, "bottom_right_x": 0.9, "bottom_right_y": 0.95 }
    ],
    "time_segment_filter": {
      "mode": "selected",
      "segments": [
        { "start_time": 0.0, "end_time": 12.5 },
        { "start_time": 30.0, "end_time": 45.0 }
      ]
    },
    "subtitle_filter": {
      "min_text_height_ratio": 0.02,
      "max_text_height_ratio": 0.15,
      "center_offset_ratio": 0.3
    }
  }'
```

```python Python
import requests

resp = requests.post(
    "https://api.looprouter.com/api/aimediakit/api/v1/tools/erase-video-subtitle-pro",
    headers={"Authorization": "Bearer sk-你的APIKey"},
    json={
        "video_url": "https://example.com/source.mp4",
        "erase_ratio_location": [
            {"top_left_x": 0.1, "top_left_y": 0.82,
             "bottom_right_x": 0.9, "bottom_right_y": 0.95},
        ],
    },
)
print(resp.json())  # {"success": true, "task_id": "...", "request_id": "..."}
```

</CodeGroup>

<Tip>
最简调用只需 `video_url` 一个字段——模型版本、模式、编码取向都有默认值，且默认全画面、全片自动识别擦除。
</Tip>

## 响应

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

拿到 `task_id` 后轮询 [任务查询接口](/video-processing/aimediakit/get-task)。字幕擦除任务成功后，结果包含成片 `video_url` 与 `duration`（不含 `resolution` / `fps` 字段，输出保持源视频规格）。

## 相关页面

<CardGroup cols={2}>
  <Card title="任务查询" icon="magnifying-glass" href="/video-processing/aimediakit/get-task">
    轮询任务状态、获取成片链接
  </Card>
  <Card title="接入说明" icon="rocket" href="/video-processing/aimediakit/overview">
    鉴权、统一响应结构与错误码
  </Card>
</CardGroup>