去水印 / 去字幕

去除视频中的水印、Logo、硬字幕等叠加元素。可以一次请求直接处理，也可以先检测候选区域、由用户确认后再处理；支持 ffmpeg（区域模糊）和 raft（内容修复）两种算法。

示例效果

`subtitle` 模式

处理前

处理后

`full_screen` 模式

处理前

处理后

选择调用方式

同一个接口 POST /task/video_purify 支持两种用法，用请求里是否传 phase 区分：

调用方式	怎么调用	适合场景	得到什么
方式一：一次性处理	1 次请求，不传 `phase`	已经确定要去字幕、全屏去文字，或已知要去除的区域	处理后的视频
方式二：检测确认	2 次请求：先 `phase=detect`，用户在客户端确认后再 `phase=purify`	想先看系统找到了哪些文字，再由用户删除误检、调整或补充区域	第 1 次得到候选区域 JSON 文件，第 2 次得到处理后的视频

两种方式的请求参数各自独立。确定方式后，在「创建任务」中只看对应请求的参数表即可。方式二的两次请求各自创建任务，分别按视频时长计费。

检测确认流程

检测：客户端发送 phase=detect 请求，指定扫描全屏、字幕区域或一块自定义区域。系统返回候选文字区域的 JSON 文件，不生成视频。一个视频可能有数千个候选。目前只检测文字，图形 Logo、半透明图案需要用户手动补框。
确认：客户端展示候选区域，由用户编辑出一份最终清单：
- 删除误检：从清单中移除该候选。如果它和其他保留的区域重叠，还需要为它添加保护区域，否则重叠部分仍会被处理。
- 调整位置、大小或时间：修改该区域的坐标、宽高或 start / end。
- 新增区域：手动画一个框（source=manual），框内全部内容在指定时间内都会被去除。
- 保护画面：把不能被改动的画面加入保护清单 protect_regions。
处理：客户端以 phase=purify 提交最终清单。服务端只处理清单里的区域，不会重新检测，也不会自动加回被删除的候选。

ℹ️ 说明：这里的“客户端”指调用方自行开发和维护的 GUI（Web、桌面客户端或移动 App），同合云不提供。视频预览、候选展示、区域增删改、时间调整和最终提交都由调用方实现；同合云接口只负责检测和处理。

创建任务

基本信息

项目	值
请求方法	`POST`
请求路径	`/task/video_purify`
Content-Type	`application/json`
鉴权方式	`Authorization` 请求头（直接传 API Key）

三种请求共用这个地址，请求体各不相同：

请求	`phase`	用途
一次性处理	不传	方式一，直接生成处理后的视频
检测	`detect`	方式二第 1 步，只返回候选区域
按清单处理	`purify`	方式二第 2 步，按最终清单生成处理后的视频；已知坐标时也可跳过检测直接调用

💡 提示：每种请求只读取自己参数表里的字段，传入的其他字段会被忽略，不会改变处理方式。例如不传 phase 且 purify_scope=subtitle 时，即使同时传了 regions 也只去字幕。

输入视频要求

创建任务前会先检查输入视频。不满足要求时直接返回错误码，不创建任务、不扣费：

项目	要求	不满足时的错误码
时长	不超过 2 小时；使用 `raft` 算法时不超过 20 分钟	`6019`；`raft` 超过 20 分钟返回 `6016`
分辨率	宽和高都不超过 4000 像素，常见的 3840×2160 可以处理，4096×2160 会超限；使用 `raft` 算法时短边不小于 128 像素	`6022`；`raft` 短边过小返回 `6035`
帧率	不超过 120 fps	`6023`
文件完整性	文件能被正常解析和解码	`6017` / `6021`

raft 的两项限制只在实际处理时检查，检测请求和空清单处理不受影响。

一次性处理

不传 phase，由 purify_scope 决定处理模式。

请求参数

参数名	类型	必填	默认值	说明
`file_id`	`string`	是	—	已上传视频文件的 ID
`purify_scope`	`string`	否	`full_screen`	处理模式：`full_screen` / `subtitle` / `custom` / `region`，见下表
`rois`	`array`	`purify_scope=custom` 时是	—	识别范围列表，可以是一个或多个，每项结构见「区域对象」；此时 `id`、`source` 不需要，`start`、`end` 可省略。只在范围内识别文字并去除，范围外的画面不处理
`regions`	`array`	`purify_scope=region` 时是	—	要直接去除的区域列表，每项结构见「区域对象」；此时 `id`、`source` 不需要，`start`、`end` 可省略
`purify_func_type`	`string`	否	`ffmpeg`	处理算法：`ffmpeg` 为区域模糊，速度快；`raft` 为内容修复补全，仅支持 20 分钟以内视频，不保证还原被遮挡前的真实画面

处理模式

`purify_scope`	处理方式	需要的参数
`full_screen`	在整个画面中识别文字并去除	—
`subtitle`	只识别并去除字幕区域的文字	—
`custom`	只在 `rois` 给出的一个或多个范围内识别文字并去除，每个范围可限定时间段；范围内的其他内容和范围外的画面都保持原样	`rois`
`region`	不做识别，`regions` 框内的全部内容（包括画面主体）都会被处理，可限定时间段。适合图形台标、半透明图案、艺术字等识别不到的元素，以及只在某段时间出现的角标	`regions`

💡 提示：使用 region 模式时，框越小、越贴近要去除的元素，效果越好。框的边缘会有几个像素的柔和过渡。

💡 提示：使用 custom 模式时，多个范围只检测一次，按视频时长计费一次；文字跨出范围时只处理范围内的部分。范围尽量贴近要去除的文字，效果更好。

请求示例

subtitle 模式（去除字幕）：

curl -X POST https://api.ai-mcn.tv:10000/task/video_purify \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "purify_scope": "subtitle",
    "purify_func_type": "raft"
  }'

custom 模式（底部 20% 区域内的文字全程去除，左上角的标题文字只去前 10 秒）：

curl -X POST https://api.ai-mcn.tv:10000/task/video_purify \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "purify_scope": "custom",
    "rois": [
      {"x": 0.0, "y": 0.78, "w": 1.0, "h": 0.2},
      {"x": 0.02, "y": 0.02, "w": 0.3, "h": 0.1, "start": 0, "end": 10}
    ]
  }'

region 模式（去除右上角角标的前 5 秒，以及底部区域从第 120 秒到结尾）：

curl -X POST https://api.ai-mcn.tv:10000/task/video_purify \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "purify_scope": "region",
    "purify_func_type": "raft",
    "regions": [
      {"x": 0.8, "y": 0.02, "w": 0.18, "h": 0.08, "start": 0, "end": 5},
      {"x": 0.3, "y": 0.85, "w": 0.4, "h": 0.1, "start": 120}
    ]
  }'

检测

方式二第 1 步。只返回候选区域，不生成视频；按视频时长计费。

请求参数

参数名	类型	必填	默认值	说明
`file_id`	`string`	是	—	已上传视频文件的 ID
`phase`	`string`	是	—	固定为 `detect`
`detect_scope`	`string`	否	`full_screen`	检测范围：`full_screen`（全屏）/ `subtitle`（字幕区域）/ `custom`（由 `detect_roi` 指定）
`detect_roi`	`object`	`detect_scope=custom` 时是	—	检测范围 `{"x","y","w","h"}`，取值要求同「区域对象」的 `x`、`y`、`w`、`h`

检测请求不需要 purify_func_type，处理算法在第 2 步选择。

请求示例

全屏检测：

curl -X POST https://api.ai-mcn.tv:10000/task/video_purify \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "phase": "detect",
    "detect_scope": "full_screen"
  }'

只检测底部 25% 区域：

curl -X POST https://api.ai-mcn.tv:10000/task/video_purify \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "phase": "detect",
    "detect_scope": "custom",
    "detect_roi": {"x": 0.0, "y": 0.75, "w": 1.0, "h": 0.25}
  }'

任务完成后，通过「查询任务结果」获取检测结果文件的下载地址，文件结构见「检测结果文件」。

按清单处理

方式二第 2 步，提交用户确认后的最终清单并生成处理后的视频。已知要处理的坐标、且需要保护区域时，也可以跳过检测直接调用。

请求参数

参数名	类型	必填	默认值	说明
`file_id`	`string`	是	—	已上传视频文件的 ID
`phase`	`string`	是	—	固定为 `purify`
`regions`	`array`	是	—	最终去除清单，每项结构见「区域对象」，所有字段都必须提供。可以是空数组，表示不处理任何区域
`protect_regions`	`array`	否	`[]`	保护清单，结构同 `regions`；与去除区域重叠时保护优先
`source_file_id`	`string`	否	—	检测结果文件里的 `source.file_id`；传入时必须与 `file_id` 一致，用于防止把一个视频的检测结果提交给另一个视频
`purify_func_type`	`string`	否	`ffmpeg`	处理算法，同「一次性处理」

处理规则

实际处理范围 = 所有去除区域的并集 − 所有保护区域的并集。删除一个候选不会抵消与它重叠的其他去除区域，需要保留的画面请添加保护区域。
服务端只按清单处理，不会重新检测，也不会自动加回被删除的候选。
regions 为空数组时，服务端直接复制原文件，不转码、不启动修复；任务仍按视频时长计费，查询结果中 unchanged 为 true。
支持提交数千个区域；超出视频时长、分辨率或请求体等服务端资源限制时返回 6016。
保护区域、精确范围处理和空清单直接复制需要服务端协议版本 2，可先通过「查询协议能力」确认。

请求示例

提交检测确认后的清单（保留一个检测结果，并新增一个手动区域）：

curl -X POST https://api.ai-mcn.tv:10000/task/video_purify \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "source_file_id": "537489015178246",
    "phase": "purify",
    "purify_func_type": "raft",
    "regions": [
      {"id": "det-000001", "source": "detected", "x": 0.70, "y": 0.04, "w": 0.22, "h": 0.09, "start": 0.0, "end": 5.2},
      {"id": "manual-000001", "source": "manual", "x": 0.05, "y": 0.05, "w": 0.25, "h": 0.20, "start": 2.0, "end": 8.0}
    ]
  }'

不检测，直接去除已知角标并保护与之重叠的文字（示例坐标需按实际视频调整）：

curl -X POST https://api.ai-mcn.tv:10000/task/video_purify \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "phase": "purify",
    "purify_func_type": "ffmpeg",
    "regions": [
      {"id": "corner-1", "source": "manual", "x": 0.8, "y": 0.02, "w": 0.18, "h": 0.08, "start": 0, "end": 5}
    ],
    "protect_regions": [
      {"id": "keep-1", "source": "manual", "x": 0.8, "y": 0.08, "w": 0.08, "h": 0.02, "start": 2, "end": 5}
    ]
  }'

区域对象

regions、rois 和 protect_regions 的每一项都是区域对象。一次性处理和按清单处理对字段的要求不同：

字段	类型	一次性处理（`region` / `custom` 模式）	按清单处理	说明
`id`	`string`	不需要	必填	区域唯一标识，同一份清单内不能重复。检测结果自带 `det-000001` 形式的 ID，客户端新增区域时自行生成
`source`	`string`	不需要	必填	`detected`（检测得到）或 `manual`（手动新增）
`x`、`y`	`number`	必填	必填	区域左上角坐标，0-1 归一化画面比例
`w`、`h`	`number`	必填	必填	区域宽高，0-1 归一化画面比例，需大于 0，且 `x+w≤1`、`y+h≤1`
`start`	`number`	选填，默认 `0`	必填	开始时间（秒，从视频开头算起），需 ≥0 且小于视频时长
`end`	`number`	选填，默认到视频结尾	必填	结束时间（秒），需大于 `start`；超过视频时长时按结尾处理

坐标相对于旋转校正后的显示画面，即播放器中看到的方向。
时间区间为左闭右开 [start, end)。
区域可以重叠，服务端会在内部合并遮罩，但不会修改调用方提交的清单。
按清单处理时，修改只写入区域范围内，边缘的柔和过渡也不会进入保护区域；但有损视频编码仍可能轻微改变邻近像素，不保证逐像素一致。可变帧率（VFR）视频按固定帧率（CFR）输出。

检测结果文件

检测任务完成后，从 output_result.regions_download_url 下载。文件结构如下：

{
  "version": 1,
  "source": {"file_id": "537489015178246"},
  "video": {
    "width": 1920,
    "height": 1080,
    "duration": 120.0,
    "fps": 30,
    "fps_exact": "30/1"
  },
  "regions": [
    {"id": "det-000001", "source": "detected", "x": 0.7, "y": 0.04, "w": 0.22, "h": 0.09, "start": 0.0, "end": 5.2, "score": 0.9132}
  ]
}

字段	说明
`version`	文件格式版本，当前为 `1`
`source.file_id`	被检测视频的文件 ID，可作为按清单处理时的 `source_file_id`
`video`	视频宽高、时长（秒）和帧率；`fps_exact` 为精确的分数帧率，如 `30000/1001`
`regions`	候选区域数组，可能有数千项。每项已包含按清单处理所需的全部字段，编辑后可直接作为 `regions` 提交；另带 `score`（0-1），表示这一块是文字的把握程度，越高越像文字

score 可用来筛掉误检，例如客户端只展示 score 不低于某个值的候选，阈值依视频而定。字幕、标题这类真实文字的 score 同样会高，因此 score 只说明「像不像文字」，该去除哪些文字仍由用户判断。个别情况下拿不到置信度时，候选不带 score，请按无分数处理。检测结果不提供识别出的文字内容。

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "task_type": "video_purify",
    "status": "queued"
  }
}

查询任务结果

基本信息

项目	值
请求方法	`GET`
请求路径	`/task/video_purify/{task_id}`
鉴权方式	`Authorization` 请求头（直接传 API Key）

响应参数（output_result）

检测任务和处理任务返回的字段不同：

参数名	类型	说明
`phase`	`string`	传了 `phase` 的任务返回 `detect` 或 `purify`；一次性处理任务不返回
`file_id`	`string`	处理任务返回：处理后的视频文件 ID
`download_url`	`string`	处理任务返回：处理后视频的下载路径
`unchanged`	`boolean`	按清单处理且 `regions` 为空数组时返回 `true`，表示输出是原文件的副本
`regions_file_id`	`string`	检测任务返回：检测结果 JSON 文件 ID
`regions_download_url`	`string`	检测任务返回：检测结果 JSON 文件下载路径
`region_count`	`number`	检测任务返回：候选区域数量，可能达到数千
`video`	`object`	检测任务返回：视频元数据，包含 `width`、`height`、`duration`、`fps`、`fps_exact`

成功响应示例

处理任务完成：

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "file_id": "537489015178248",
      "download_url": "/download/a1/output.mp4"
    },
    "create_time": "2026-04-05T08:00:00Z",
    "update_time": "2026-04-05T08:01:00Z"
  }
}

检测任务完成：

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178250",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "phase": "detect",
      "regions_file_id": "537489015178249",
      "regions_download_url": "/download/a1/regions.json",
      "region_count": 2387,
      "video": {
        "width": 1920,
        "height": 1080,
        "duration": 120.0,
        "fps": 30,
        "fps_exact": "30/1"
      }
    },
    "create_time": "2026-04-05T08:00:00Z",
    "update_time": "2026-04-05T08:00:40Z"
  }
}

查询协议能力

保护区域、精确范围处理和空清单直接复制需要服务端协议版本 2。使用前可调用此接口确认返回 data.review_protocol 为 2。该接口需要鉴权，不创建任务、不计费。

curl https://api.ai-mcn.tv:10000/task/video_purify/capabilities \
  -H "Authorization: YOUR_API_KEY"

{
  "code": 200,
  "msg": "success",
  "data": {
    "review_protocol": 2
  }
}

通过 gtrk CLI 调用

Agent 可以用 gtrk purify 命令完成同样的流程：

命令	作用
`gtrk purify detect video.mp4 --json`	检测，获取完整区域文件与摘要
`gtrk purify edit regions.json --delete-id det-000001 --out final.json`	编辑区域清单
`gtrk purify apply final.json --json`	按清单处理
`gtrk purify run video.mp4 --detect-scope subtitle --json`	处理范围已明确时，一步完成
`gtrk purify resume journal.json --json`	复用已提交的任务

CLI 提交处理请求前会检查服务端是否支持所需的协议能力。
最终清单为空时，CLI 在本地直接返回源文件，不提交处理任务。
提交响应丢失时，CLI 会停止并要求核对云端任务，不会自动重新提交。

错误码

错误码	HTTP 状态码	说明	解决方案
`6013`	400	`file_id` 缺失	传入 `file_id` 参数
`6016`	400	参数或区域非法：当前请求所需参数缺失、坐标越界、`end` 不大于 `start`、区域数量或请求体超过服务端资源限制，或 `raft` 模式视频时长超过 20 分钟	对照所用请求的参数表和「区域对象」检查参数；大规模任务超出资源限制时请拆分任务或缩小视频范围；`raft` 模式视频需在 20 分钟以内
`6014`	400	文件类型与接口不匹配	传入视频文件
`6004`	404	文件不存在	检查 `file_id` 是否正确
`6017`	400	视频文件无法解析：文件损坏、格式异常，或帧率等元信息互相矛盾	用剪辑或转码工具重新导出后上传
`6019`	400	视频时长为 0 或超过 2 小时	截短视频后重新上传
`6021`	400	视频完整性校验失败：部分位置无法解码，或文件末尾不完整	更换源文件，或重新导出完整视频后上传
`6022`	400	视频分辨率超过限制：宽或高超过 4000 像素	将视频缩放到宽和高都不超过 4000 像素后重新上传
`6023`	400	视频帧率超过 120 fps	将视频转为 120 fps 以内（如 60 fps）后重新上传
`6035`	400	视频画面短边过小：`raft` 模式要求画面短边 ≥128 像素（报错信息会写明当前尺寸）	改用 `purify_func_type: ffmpeg`，或提供画面更大的源片
`6502`	401	鉴权失败	检查 `Authorization` 请求头
`6202`	402	余额不足	前往仪表盘充值

去水印 / 去字幕

示例效果

subtitle 模式

full_screen 模式

选择调用方式

检测确认流程

创建任务

基本信息

输入视频要求

一次性处理

请求参数

处理模式

请求示例

检测

请求参数

请求示例

按清单处理

请求参数

处理规则

请求示例

区域对象

检测结果文件

成功响应示例

查询任务结果

基本信息

响应参数（output_result）

成功响应示例

查询协议能力

通过 gtrk CLI 调用

错误码

`subtitle` 模式

`full_screen` 模式