# 创建字幕擦除任务

对已生成的视频做 AI 精细化字幕擦除，异步返回任务 ID。

**完成通知 —— 二选一**：
- 配 `callback_url` → 任务终态时 XRToken 主动 POST 通知你，无需轮询
- 不配 → 自行 `GET /v1/videos/erase-subtitle/{taskId}` 轮询结果

**输入约束**：只能擦除通过 XRToken 生成的视频，且生成时间
< 23 小时。调用方传 `video_task_id`，其他的 XRToken 处理。

**擦除耗时**：不排队情况下一般 20–30 分钟内完成；高峰排队时
可能延长到 2–3 小时。建议使用 `callback_url` 避免长轮询。

**支持擦除的字幕**：
- 垂直位置：画面 **下半部分** 的横向字幕
- 字号：单字竖向高度为视频高度的 **1% – 10%**
- 语言：中文 / 英文

**不支持**（以下情况不会被擦除）：
- 位于画面 **上半部分** 的字幕
- 字号过小（< 1% 高度）或过大（> 10% 高度）
- 中英文之外的语言 / 无法识别语种的文本

**可能误擦的场景**：画面下半部分出现的符合尺寸阈值的场景文本
（例如条幅、招牌文字）也会被识别为字幕一并擦除。建议调用方
在上游视频生成阶段就控制这类文本的出现位置。

**计费**：按视频秒数计费；当前免费推广期，每次调用产生 ¥0.00 的
消费记录（可在账单页查询）。擦除完成后，结果视频自动写入素材库，
与原视频并列展示。

## POST /v1/videos/erase-subtitle

> Create subtitle erase task

Erase hard-coded subtitles from a video you previously generated via
XRToken. Async.

**Completion notification — pick one**:
- Set `callback_url` → XRToken POSTs you on terminal state, no polling
- Or poll `GET /v1/videos/erase-subtitle/{taskId}` yourself

**Input constraint**: only works for videos generated through XRToken,
and only within 23 hours of generation. Pass the `video_task_id` —
XRToken handles the rest.

**Processing time**: typically under 20–30 minutes when queues are
idle; may stretch to 2–3 hours under peak load. Use `callback_url`
to avoid long-polling.

**Subtitles that WILL be erased**:
- Vertical position: horizontal subtitles in the **bottom 50%** of the frame
- Font size: character height between **1% and 10%** of the video height
- Language: Chinese or English

**Subtitles that WON'T be erased**:
- Text in the **top 50%** of the frame
- Text that is too small (< 1% height) or too large (> 10% height)
- Languages other than Chinese / English, or unrecognized scripts

**May be incorrectly erased**: scene text that sits in the bottom
half and meets the size thresholds (banners, signage) is treated
as subtitles and gets erased. Control such text at generation time
if possible.

**Billing**: per video second; currently free during rollout. Each
call still writes a zero-amount freeze/settle pair to the ledger so
billing history reflects every call. The erased clip is automatically
inserted into the gallery alongside the original.

### Authentication

`Authorization: Bearer tr-xxx`

### Request Body

Content-Type: `application/json`

- **video_task_id** `string` **(required)**  
  Video generation task ID — the `id` field returned by
- **callback_url** `string`  
  Optional. When the task reaches a terminal state (succeeded or

### Response

- **id** `string` **(required)**  
  Subtitle-erase task ID (use to poll status)
- **upstream_id** `string`  
  Upstream Volcengine task ID
- **status** ``processing`` **(required)**  
  
- **created_at** `string` **(required)**  
  

### Error Codes

- `400`: 
- `401`: 
- `402`: 
- `429`: 
- `502`: