视频去水印快速版接口文档

对固定位置的水印做逐帧局部修补,输出保持源分辨率、帧率和音轨。异步受理,完成后查询或回调。

对固定位置的水印或硬字幕做逐帧修补:只在指定区域内用 LaMa、STTN 或 OpenCV 补洞,其它区域不动。输出保持源分辨率、源帧率,并保留原音轨。成片为 MP4,不带平台水印。

本接口是异步的:提交后拿到任务号,再查询结果;请求里带了回调地址时,任务结束会再 POST 同一份结果。受理后直接处理,不进入长任务排队池。

和视频去水印是两个接口,按画面情况选:

视频去水印快速版(本文档)视频去水印
处理方式逐帧局部修补,只改指定区域整帧重绘
输出分辨率与源片一致长边压到 768,宽高对齐 32
帧率与源片一致固定 16fps
音轨保留保留
输入MP4、MOV、WebM。不支持 m3u8见视频去水印。长视频可自动切片,并可传 m3u8
适用台标、角标、固定字幕条、横幅水印位置不固定,或面积很大、需要重绘背景

水印位置固定、只抹掉那一块、画质和帧率都要保持源片时,用本接口。水印到处跑或面积很大时,用视频去水印。

方法与路径产品编码说明
POST /api/video_remove_watermark_vsrvideo_remove_watermark_vsr提交视频去水印快速版任务
GET /api/tasks/{request_id}—查询任务

不填回调地址也可以提交,结果用查询接口获取。

环境根地址
测试https://test-star-api.aiaibase.com
正式https://star-api.aiaibase.com

路径接在根地址后面。例如测试环境提交:

text
POST https://test-star-api.aiaibase.com/api/video_remove_watermark_vsr

请求体为 JSON,Content-Type: application/json。认证只使用请求头:

text
Authorization: Bearer {API Key}

{API Key} 由平台签发,只能放在服务端。浏览器或前端仓库里不要出现 Key,由自己的后端转发。测试 Key 向平台单独申请,不要复用线上 Key。

输入必须是服务端能直接下载的 http 或 https 地址。处理期间地址必须有效,签名地址要把有效期留够。支持 MP4、MOV、WebM,不支持 m3u8。建议单文件不超过 100MiB。需要登录或签名过期的地址会处理失败。

需要整帧重绘或处理长视频、m3u8 时,使用视频去水印。需要去掉图片水印时,使用图片去水印。

所有响应都是同一结构。业务结果看 success 和 error.code。

字段类型说明
successbool受理成功、处理中、处理成功为 true;失败为 false
dataobject成功或处理中的业务数据。失败时不返回
errorobject失败时的错误。含 code、message,参数错误时还有 details
meta.request_idstring平台任务号。查询和排查都用这个值
meta.timestampstring响应时间
json
{
  "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否stringauto检测模式:auto、rectangle、mask。见下方三种模式
method否stringLaMa修补算法:LaMa、STTN、OpenCV。区分大小写
region_x否number0.75修复区左上角 X,按画面宽度归一化,0–1
region_y否number0修复区左上角 Y,按画面高度归一化,0–1
region_width否number0.25修复区宽度比例,0–1
region_height否number0.25修复区高度比例,0–1
padding否int8文字遮罩外扩像素,0–128。只在 detection 为 auto 时可传
mask_url条件string—黑白 PNG 地址。只在 detection 为 mask 时必填。白为修复、黑为保留,尺寸必须与视频帧一致
video_format否stringvideo/h264-mp4输出编码:video/h264-mp4、video/h265-mp4
is_encrypt否boolfalse是否加密交付。见下方加密交付
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 里给出字段:

json
{
  "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。

底部硬字幕用整条底边:

json
{
  "detection": "auto",
  "region_x": 0,
  "region_y": 0.75,
  "region_width": 1,
  "region_height": 0.25,
  "padding": 8
}

rectangle:不检测,直接把整个矩形区域修补掉。适合位置固定、形状规则的台标或角标。

json
{
  "detection": "rectangle",
  "region_x": 0.8,
  "region_y": 0.02,
  "region_width": 0.18,
  "region_height": 0.12
}

mask:传一张与视频帧同宽同高的黑白 PNG,白色区域修复,黑色区域保留,所有帧共用这一张。region_* 和 padding 不参与计算。换分辨率就要换 mask,尺寸不一致会失败。本接口不能上传一张水印图自动匹配,按形状修补时需要自己做这张 PNG。

json
{
  "detection": "mask",
  "mask_url": "https://cdn.example.com/mask-1920x1080.png",
  "method": "STTN"
}

受理返回

此时成片还没生成。保存 meta.request_id 用于查询。

字段类型说明
data.statusstring固定为 accepted
data.client_request_idstring调用方请求号。没传时可能不返回
meta.request_idstring平台任务号
json
{
  "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"
  }
}

请求示例

固定矩形区域:

bash
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"
  }'

底部字幕,自动检测:

bash
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

只能查询当前密钥自己的任务。

bash
curl 'https://test-star-api.aiaibase.com/api/tasks/{request_id}' \
  -H 'Authorization: Bearer {API Key}'

处理中。这里的 data.status 是字符串 accepted,不是数字:

json
{
  "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 是对象数组,结构见下方加密交付。两种形态不要混用。

明文成功

json
{
  "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。这些字段不稳定。程序只依赖本文档列出的字段。成片地址拿到后尽快转存。

失败

json
{
  "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-Typeapplication/json
成功条件回调地址返回 HTTP 2xx
重试非 2xx 或连接失败时,30 秒后重试,最多 4 次

用 meta.request_id 对应自己的业务单。成功时按 data.is_encrypt 读取 data.out_data。

is_encrypt 为 true 时,产物走加密链路。默认 false,需要可直接下载的 MP4 时不要打开。

json
{
  "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业务码说明
4001001参数错误。未知字段、取值非法、区域越界、padding 或 mask_url 出现在不允许的模式里。看 error.details[].field
4004102缺少必填字段,例如 video_url,或 detection 为 mask 时缺少 mask_url
4004107video_url 或 mask_url 不是合法的 http 或 https 链接。m3u8 源也会被拒绝
4011102缺少 Authorization
4015003API Key 无效或已停用
2005204未开通该产品
2003600上游处理失败。源不可达、解码失败、mask 尺寸不一致或模型报错。不计费
2009001系统负载过高,稍后重试
4094003同一调用方请求号,请求体不同
5001500服务器内部错误。排查时带上 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,时长与源片一致
bash
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。