视频去水印快速版接口文档
对固定位置的水印做逐帧局部修补,输出保持源分辨率、帧率和音轨。异步受理,完成后查询或回调。
对固定位置的水印或硬字幕做逐帧修补:只在指定区域内用 LaMa、STTN 或 OpenCV 补洞,其它区域不动。输出保持源分辨率、源帧率,并保留原音轨。成片为 MP4,不带平台水印。
本接口是异步的:提交后拿到任务号,再查询结果;请求里带了回调地址时,任务结束会再 POST 同一份结果。受理后直接处理,不进入长任务排队池。
和视频去水印是两个接口,按画面情况选:
| 视频去水印快速版(本文档) | 视频去水印 | |
|---|---|---|
| 处理方式 | 逐帧局部修补,只改指定区域 | 整帧重绘 |
| 输出分辨率 | 与源片一致 | 长边压到 768,宽高对齐 32 |
| 帧率 | 与源片一致 | 固定 16fps |
| 音轨 | 保留 | 保留 |
| 输入 | MP4、MOV、WebM。不支持 m3u8 | 见视频去水印。长视频可自动切片,并可传 m3u8 |
| 适用 | 台标、角标、固定字幕条、横幅 | 水印位置不固定,或面积很大、需要重绘背景 |
水印位置固定、只抹掉那一块、画质和帧率都要保持源片时,用本接口。水印到处跑或面积很大时,用视频去水印。
| 方法与路径 | 产品编码 | 说明 |
|---|---|---|
POST /api/video_remove_watermark_vsr | video_remove_watermark_vsr | 提交视频去水印快速版任务 |
GET /api/tasks/{request_id} | — | 查询任务 |
不填回调地址也可以提交,结果用查询接口获取。
| 环境 | 根地址 |
|---|---|
| 测试 | https://test-star-api.aiaibase.com |
| 正式 | https://star-api.aiaibase.com |
路径接在根地址后面。例如测试环境提交:
POST https://test-star-api.aiaibase.com/api/video_remove_watermark_vsr请求体为 JSON,Content-Type: application/json。认证只使用请求头:
Authorization: Bearer {API Key}{API Key} 由平台签发,只能放在服务端。浏览器或前端仓库里不要出现 Key,由自己的后端转发。测试 Key 向平台单独申请,不要复用线上 Key。
输入必须是服务端能直接下载的 http 或 https 地址。处理期间地址必须有效,签名地址要把有效期留够。支持 MP4、MOV、WebM,不支持 m3u8。建议单文件不超过 100MiB。需要登录或签名过期的地址会处理失败。
所有响应都是同一结构。业务结果看 success 和 error.code。
| 字段 | 类型 | 说明 |
|---|---|---|
success | bool | 受理成功、处理中、处理成功为 true;失败为 false |
data | object | 成功或处理中的业务数据。失败时不返回 |
error | object | 失败时的错误。含 code、message,参数错误时还有 details |
meta.request_id | string | 平台任务号。查询和排查都用这个值 |
meta.timestamp | string | 响应时间 |
{
"success": false,
"error": { "code": 4102, "message": "视频地址必填" },
"meta": { "request_id": "…", "timestamp": "…" }
}调用方请求号:
- 字段为
client_request_id。建议每次提交都带。 - 这是调用方自己的单号,和响应里的
meta.request_id不是同一个值。 - 同一密钥下,相同调用方请求号且请求体完全一致时,返回首次任务,不会重复建单。
- 同一密钥下,调用方请求号相同但请求体不同,返回 HTTP 409,业务码
4003。换一个请求号,或把请求体改回第一次。 - 不带
client_request_id时,每次提交都会新建一单。
受理成功只表示任务已收下,成片还没生成,此时 data.status 为字符串 accepted。5 秒左右的短片通常几十秒内出结果。拿结果有两种方式,可以同时用:
- 轮询
GET /api/tasks/{request_id}。5 秒一次起步,30 秒后放宽到 15–30 秒。 - 提交时传
notify_url(或别名callback_url、notice_url)。任务进入终态后,平台 POST 一份与查询接口相同的 JSON。对方返回 HTTP 2xx 视为成功,否则 30 秒后重试,最多 4 次。
多数场景直接挂回调,轮询作兜底。回调可能重复,按 meta.request_id 做幂等。回调地址需公网可达。
- 方法:
POST - 路径:
/api/video_remove_watermark_vsr - 产品编码:
video_remove_watermark_vsr
请求参数
| 字段 | 必填 | 类型 | 默认 | 说明 |
|---|---|---|---|---|
video_url | 是 | string | — | 源视频地址,http 或 https。不支持 m3u8 |
detection | 否 | string | auto | 检测模式:auto、rectangle、mask。见下方三种模式 |
method | 否 | string | LaMa | 修补算法:LaMa、STTN、OpenCV。区分大小写 |
region_x | 否 | number | 0.75 | 修复区左上角 X,按画面宽度归一化,0–1 |
region_y | 否 | number | 0 | 修复区左上角 Y,按画面高度归一化,0–1 |
region_width | 否 | number | 0.25 | 修复区宽度比例,0–1 |
region_height | 否 | number | 0.25 | 修复区高度比例,0–1 |
padding | 否 | int | 8 | 文字遮罩外扩像素,0–128。只在 detection 为 auto 时可传 |
mask_url | 条件 | string | — | 黑白 PNG 地址。只在 detection 为 mask 时必填。白为修复、黑为保留,尺寸必须与视频帧一致 |
video_format | 否 | string | video/h264-mp4 | 输出编码:video/h264-mp4、video/h265-mp4 |
is_encrypt | 否 | bool | false | 是否加密交付。见下方加密交付 |
bid | 否 | string | — | 业务编号,最多 200 字,原样回传 |
title | 否 | string | — | 任务标题,最多 200 字,原样回传 |
client_request_id | 否 | string | — | 调用方请求号。建议必带 |
notify_url | 否 | string | — | 完成回调地址 |
callback_url | 否 | string | — | notify_url 的别名 |
notice_url | 否 | string | — | notify_url 的别名 |
表外字段会返回 HTTP 400,业务码 1001。
region_x、region_y、region_width、region_height 都是画面比例,不是像素。region_x、region_y 是左上角,region_width、region_height 是宽高占比。
约束:
region_x + region_width不能超过 1,region_y + region_height不能超过 1。detection为mask时不校验区域。mask_url只在detection为mask时允许出现,且此时必填。padding只在detection为auto时允许出现。method、detection、video_format只能取上表列出的值。
违反约束返回 HTTP 400,业务码 1001,error.details 里给出字段:
{
"success": false,
"error": {
"code": 1001,
"message": "region_x + region_width 不能超过 1",
"details": [
{
"field": "region_width",
"message": "region_x + region_width 不能超过 1"
}
]
}
}三种检测模式
auto(默认):在指定区域内逐帧检测文字再修补。没检测到文字的帧保持原画。默认区域是画面右上角四分之一(region_x 0.75,region_y 0,region_width 0.25,region_height 0.25)。水印不是文字(例如图形标志)时,检测不到就不会修,改用 rectangle 或 mask。
底部硬字幕用整条底边:
{
"detection": "auto",
"region_x": 0,
"region_y": 0.75,
"region_width": 1,
"region_height": 0.25,
"padding": 8
}rectangle:不检测,直接把整个矩形区域修补掉。适合位置固定、形状规则的台标或角标。
{
"detection": "rectangle",
"region_x": 0.8,
"region_y": 0.02,
"region_width": 0.18,
"region_height": 0.12
}mask:传一张与视频帧同宽同高的黑白 PNG,白色区域修复,黑色区域保留,所有帧共用这一张。region_* 和 padding 不参与计算。换分辨率就要换 mask,尺寸不一致会失败。本接口不能上传一张水印图自动匹配,按形状修补时需要自己做这张 PNG。
{
"detection": "mask",
"mask_url": "https://cdn.example.com/mask-1920x1080.png",
"method": "STTN"
}受理返回
此时成片还没生成。保存 meta.request_id 用于查询。
| 字段 | 类型 | 说明 |
|---|---|---|
data.status | string | 固定为 accepted |
data.client_request_id | string | 调用方请求号。没传时可能不返回 |
meta.request_id | string | 平台任务号 |
{
"success": true,
"data": {
"status": "accepted",
"client_request_id": "biz-order-20261117-001"
},
"meta": {
"request_id": "cb72acae-49de-4ada-8498-bb959986182c",
"timestamp": "2026-11-17T05:58:38Z"
}
}请求示例
固定矩形区域:
curl -X POST 'https://test-star-api.aiaibase.com/api/video_remove_watermark_vsr' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"video_url": "https://cdn.example.com/source.mp4",
"detection": "rectangle",
"method": "LaMa",
"region_x": 0.8,
"region_y": 0.02,
"region_width": 0.18,
"region_height": 0.12,
"client_request_id": "biz-order-20261117-001",
"notify_url": "https://your.host/hooks/vsr"
}'底部字幕,自动检测:
curl -X POST 'https://test-star-api.aiaibase.com/api/video_remove_watermark_vsr' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"video_url": "https://cdn.example.com/source.mp4",
"detection": "auto",
"region_x": 0,
"region_y": 0.75,
"region_width": 1,
"region_height": 0.25,
"padding": 8,
"client_request_id": "biz-order-20261117-002"
}'- 方法:
GET - 路径:
/api/tasks/{request_id} request_id:受理响应里的meta.request_id
只能查询当前密钥自己的任务。
curl 'https://test-star-api.aiaibase.com/api/tasks/{request_id}' \
-H 'Authorization: Bearer {API Key}'处理中。这里的 data.status 是字符串 accepted,不是数字:
{
"success": true,
"data": {
"status": "accepted",
"client_request_id": "biz-order-20261117-001"
},
"meta": { "request_id": "…", "timestamp": "…" }
}完成判定
完成条件是 success 为 true,data.status 为 2,且 data.error_code 为 SUCCESS。成品地址在 data.out_data。
success 为 false 表示失败,看 error.code 和 error.message。失败响应里没有 data.status。
明文交付时,out_data 是成片地址数组,取第一个元素。加密交付时,out_data 是对象数组,结构见下方加密交付。两种形态不要混用。
明文成功
{
"success": true,
"data": {
"client_request_id": "biz-order-20261117-001",
"status": 2,
"error_code": "SUCCESS",
"is_encrypt": false,
"is_watermark": false,
"out_data": ["https://images.aiaipic.win/…/video/output.mp4"],
"detection": "auto",
"method": "LaMa",
"region_x": 0.75,
"region_y": 0,
"region_width": 0.25,
"region_height": 0.25,
"padding": 8,
"video_format": "video/h264-mp4",
"video_url": "https://cdn.example.com/source.mp4",
"task_type": "video_remove_watermark_vsr"
},
"meta": { "request_id": "…", "timestamp": "…" }
}| 字段 | 说明 |
|---|---|
out_data | 成片地址数组。明文交付时每个元素是 MP4 地址 |
status | 成功为数字 2。处理中是字符串 accepted |
error_code | 成功时为 SUCCESS |
is_encrypt | 是否加密交付 |
is_watermark | 成片是否带平台水印。成功时为 false |
task_type | 固定为 video_remove_watermark_vsr |
client_request_id | 调用方请求号 |
结果里还可能带上游透传字段,例如 task_id、workflow_name、created_at、updated_at。这些字段不稳定。程序只依赖本文档列出的字段。成片地址拿到后尽快转存。
失败
{
"success": false,
"error": { "code": 3600, "message": "上游异常原文" },
"meta": { "request_id": "…", "timestamp": "…" }
}3600 表示上游处理失败,例如源地址不可达、解码失败或模型报错。失败不计费。改完源或参数后重新提交。
请求体带了 notify_url、callback_url 或 notice_url 时,任务进入终态后,平台向该地址 POST。没有回调地址时不会 POST。
| 项 | 值 |
|---|---|
| 方法 | POST |
| 请求体 | 与 GET /api/tasks/{request_id} 的响应 JSON 相同 |
Content-Type | application/json |
| 成功条件 | 回调地址返回 HTTP 2xx |
| 重试 | 非 2xx 或连接失败时,30 秒后重试,最多 4 次 |
用 meta.request_id 对应自己的业务单。成功时按 data.is_encrypt 读取 data.out_data。
is_encrypt 为 true 时,产物走加密链路。默认 false,需要可直接下载的 MP4 时不要打开。
{
"success": true,
"data": {
"status": 2,
"error_code": "SUCCESS",
"is_encrypt": true,
"encrypt_status": "completed",
"out_data": [
{
"download_url": "https://p0-static.inaiai.com/encrypt/…/stream.m3u8",
"encryption_key": "https://p0-static.inaiai.com/encrypt/…/enc.key"
}
],
"video_format": "video/h264-mp4",
"task_type": "video_remove_watermark_vsr"
},
"meta": { "request_id": "…" }
}- 加密产物是 HLS + AES-128,不是 MP4。
download_url是 m3u8 播放列表,encryption_key是 AES key。 - key 是公开 URL。支持 HLS 的播放器拿到播放列表后会自己取 key,调用方不用实现解密。
- Web 使用 hls.js,key 域名需要允许跨域。iOS / Safari 原生支持 HLS。Android 使用 ExoPlayer。
- 不能把
download_url直接放进<video src>。业务要一个可直传的 MP4 时,不要走加密交付。
| HTTP | 业务码 | 说明 |
|---|---|---|
| 400 | 1001 | 参数错误。未知字段、取值非法、区域越界、padding 或 mask_url 出现在不允许的模式里。看 error.details[].field |
| 400 | 4102 | 缺少必填字段,例如 video_url,或 detection 为 mask 时缺少 mask_url |
| 400 | 4107 | video_url 或 mask_url 不是合法的 http 或 https 链接。m3u8 源也会被拒绝 |
| 401 | 1102 | 缺少 Authorization |
| 401 | 5003 | API Key 无效或已停用 |
| 200 | 5204 | 未开通该产品 |
| 200 | 3600 | 上游处理失败。源不可达、解码失败、mask 尺寸不一致或模型报错。不计费 |
| 200 | 9001 | 系统负载过高,稍后重试 |
| 409 | 4003 | 同一调用方请求号,请求体不同 |
| 500 | 1500 | 服务器内部错误。排查时带上 meta.request_id |
按输出视频的秒数计费,档位由产物分辨率自动确定,调用方不能自选。不足 1 秒按 1 秒,其余向上取整到整秒。失败不计费。同一调用方请求号且请求体相同的重复提交不重复计费。余额不足时拒绝受理,充值后重新提交。响应里不返回金额。
本接口产物分辨率与源片一致,档位跟着源片走。
| 项 | 值 |
|---|---|
| 环境 | https://test-star-api.aiaibase.com |
| 1080p 样片 | https://download.samplelib.com/mp4/sample-5s.mp4 |
| 360p 样片 | https://download.samplelib.com/mp4/sample-5s-360p.mp4 |
| 预期 | 约几十秒后 data.status 为 2,out_data 为一条 MP4。1080p 样片产物为 1920×1080,时长与源片一致 |
BASE=https://test-star-api.aiaibase.com
curl -s -X POST "$BASE/api/video_remove_watermark_vsr" \
-H "Authorization: Bearer {API Key}" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://download.samplelib.com/mp4/sample-5s.mp4",
"detection": "rectangle",
"region_x": 0.75,
"region_y": 0,
"region_width": 0.25,
"region_height": 0.25,
"client_request_id": "demo-vsr-0001"
}'
curl -s "$BASE/api/tasks/{request_id}" \
-H "Authorization: Bearer {API Key}"success 为 true、data.status 为 2 且 data.error_code 为 SUCCESS 时,取 out_data 的第一个地址。success 为 false 时看 error.code 和 error.message。