视频去水印接口文档

提交视频地址去掉画面水印。短视频默认同一次处理;长视频可自动切片、逐片去水印再合并。按时长计费,完成后查询或回调。

提交一个视频地址,去掉画面水印。本接口是异步的:提交后拿到任务号,再查询结果;请求里带了回调地址时,任务结束会再 POST 同一份结果。

同一个接口有两种模式:

模式开启方式行为适用
单次去水印(默认)不传 auto_segment,或传 false整段视频一次送上游去水印短视频。默认只处理前 650 帧
自动切片auto_segment: true先按 segment_second 切片(默认 30 秒),逐片去水印,再合并成片。video_url 可以是 m3u8长视频。最多 180 片,视频最长 1 小时

自动切片在服务端编排。调用方仍然是提交一次、拿一个成片,不必再调视频切片与合并。

方法与路径产品编码说明
POST /api/video_remove_watermarkvideo_remove_watermark提交视频去水印任务
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

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

text
Authorization: Bearer {API Key}

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

水印位置固定、只修补指定区域并保持源分辨率和帧率时,使用视频去水印快速版。短视频用默认单次模式。长视频打开 auto_segment。需要单独拿到分段或自行合并时,使用视频切片与合并。需要去掉图片水印时,使用图片去水印。需要超清放大时,使用视频超清放大。需要从音轨生成字幕时,使用音频字幕。需要自动选择字幕轨、画面字幕或语音识别时,使用智能字幕。若只需翻译已经分好条的字幕,请使用字幕翻译。

所有响应都是同一结构。业务结果看 success 和 error.code。HTTP 状态与业务码的对应关系见错误码。

字段类型说明
successbool受理成功、处理中、处理成功为 true;失败为 false
dataobject成功或处理中的业务数据。失败时不返回
errorobject失败时的错误。含 code、message
meta.request_idstring平台任务号。查询和排查都用这个值
meta.timestampstring响应时间,例如 2026-11-04T13:26:55+08:00
json
{
  "success": false,
  "error": { "code": 4102, "message": "视频地址必填" },
  "meta": { "request_id": "…", "timestamp": "…" }
}

调用方请求号:

  • 字段可用 client_request_id,也可用别名 request_id、task_id,三选一。强烈建议每次提交都带。
  • 这是调用方自己的单号,和响应里的 meta.request_id 不是同一个值。
  • 同一密钥下,相同调用方请求号且参数完全一致时,返回原任务,不会重复扣费。
  • 同一密钥下,调用方请求号相同但参数不同,返回 HTTP 409,业务码 4003。换一个请求号,或把参数改回第一次。

受理成功只表示任务已收下,成片还没生成,此时 data.status 为字符串 accepted。处理通常要几分钟,自动切片更久。拿结果有两种方式,可以同时用:

  • 轮询 GET /api/tasks/{request_id}。建议 5–10 秒一次,间隔不要低于 3 秒,指数退避更好。
  • 提交时传 notice_url(或别名 callback_url、notify_url)。任务进入终态后,平台 POST 一份与查询接口相同的 JSON。对方返回 HTTP 2xx 视为成功,否则 30 秒后重试,最多 4 次。

前端不要把超时写死在 10 分钟以内。任务超过 24 小时仍未完成,返回 HTTP 504,业务码 3601。

  • 方法:POST
  • 路径:/api/video_remove_watermark
  • 产品编码:video_remove_watermark

请求参数

字段必填类型默认说明
video_url是string—视频地址,http 或 https,平台必须能下载。单次去水印用视频文件,建议 mp4。auto_segment 为 true 时也可以传 m3u8
auto_segment否boolfalse是否自动切片。见下方自动切片
segment_second否int30切片目标时长(秒),5–120。只在 auto_segment 为 true 时可用
m3u8_key_url否string—m3u8 解密密钥地址,http 或 https。只在 auto_segment 为 true 时可用。加密 m3u8 时与 m3u8_secret 至少传一个
m3u8_secret否string—m3u8 解密密钥。16 字节,写成 32 位十六进制。只在 auto_segment 为 true 时可用。加密 m3u8 时与 m3u8_key_url 至少传一个
unlimited否boolfalse是否取消上游 650 帧截断。auto_segment 为 true 时服务端强制开启
use_mask否boolfalse遮罩预处理。水印位置固定时画面更干净,但可能留下浅色糊斑,建议对比后再定
is_encrypt否boolfalse是否加密输出
seed否int 或 string随机随机种子,0 到 9223372036854775807。超过 9007199254740991 时用十进制字符串
bid否string—业务编号,最多 200 字
title否string—任务标题,最多 200 字
client_request_id否string—调用方请求号。建议必带
request_id否string—client_request_id 的别名
task_id否string—client_request_id 的别名
notice_url否string—完成回调地址
callback_url否string—notice_url 的别名
notify_url否string—notice_url 的别名

表外字段会返回 HTTP 400,业务码 1001。

unlimited 为 false 时,上游只处理视频的前 650 帧(60fps 约 10.8 秒,30fps 约 21.7 秒),后面的内容会被丢掉。要处理完整视频,传 unlimited: true。打开 auto_segment 后,服务端会把 unlimited 设为 true。

650 帧以内的短视频用默认单次模式。自动切片步骤更多,通常更慢。长视频要打开 auto_segment 或 unlimited,否则只会处理开头这一段。

m3u8_key_url 和 m3u8_secret 只在自动切片时可用。普通视频文件和未加密 m3u8 不用传。加密 m3u8 必须至少传一个,由后端校验。密钥地址须为 http 或 https。密钥正文是 16 字节,写成 32 位十六进制。未开 auto_segment 就传这两个字段,返回 HTTP 400,业务码 1001。

受理返回

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

字段类型说明
data.statusstring固定为 accepted
data.client_request_idstring调用方请求号
meta.request_idstring平台任务号
json
{
  "success": true,
  "data": {
    "status": "accepted",
    "client_request_id": "wm-20261104-0002"
  },
  "meta": {
    "request_id": "f18621b0-5f50-4fa8-8716-5346067773b2",
    "timestamp": "2026-11-04T13:26:55+08:00"
  }
}

单次去水印示例

bash
curl -X POST 'https://test-star-api.aiaibase.com/api/video_remove_watermark' \
  -H 'Authorization: Bearer {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "video_url": "https://cdn.example.com/source.mp4",
    "client_request_id": "wm-20261104-0001",
    "notice_url": "https://your.host/hooks/watermark"
  }'

自动切片示例

bash
curl -X POST 'https://test-star-api.aiaibase.com/api/video_remove_watermark' \
  -H 'Authorization: Bearer {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "video_url": "https://cdn.example.com/long.mp4",
    "auto_segment": true,
    "segment_second": 30,
    "client_request_id": "wm-20261104-0002"
  }'

加密 m3u8 只走自动切片。m3u8_key_url 可以代替下面的 m3u8_secret,至少传一个。

bash
curl -X POST 'https://test-star-api.aiaibase.com/api/video_remove_watermark' \
  -H 'Authorization: Bearer {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "video_url": "https://cdn.example.com/playlist.m3u8",
    "auto_segment": true,
    "segment_second": 30,
    "m3u8_secret": "00112233445566778899aabbccddeeff",
    "client_request_id": "wm-20261109-0001"
  }'

auto_segment 为 true 时,服务端按下面的顺序处理:

text
提交 → 切片 → 每片去水印 → 合并 → 完成
场景传参
默认 30 秒一片auto_segment: true
指定片长auto_segment: true,segment_second: 40
未加密 m3u8auto_segment: true,video_url 为 m3u8 地址
加密 m3u8在上一行基础上再传 m3u8_key_url 或 m3u8_secret
只传 segment_second返回 HTTP 400,业务码 1001,说明 segment_second 仅在 auto_segment=true 时可用
未开自动切片却传了 m3u8 密钥字段返回 HTTP 400,业务码 1001。m3u8_key_url、m3u8_secret 只在 auto_segment=true 时可用

segment_second 是目标片长。上游按关键帧切,实际片长可能略长,例如目标 20 秒时,实测可能切成 20.8 秒。

视频短于 segment_second 时只有 1 片,不执行合并。

进度

成功结果里的 steps 就是这条链路,可以直接展示:

json
"steps": [
  { "name": "segment", "status": "success" },
  { "name": "remove_watermark", "status": "success", "done": 2, "total": 2 },
  { "name": "merge", "status": "success" }
]

只有 1 片时没有 merge:

json
"steps": [
  { "name": "segment", "status": "success" },
  { "name": "remove_watermark", "status": "success", "done": 1, "total": 1 }
]
字段说明
steps[].namesegment、remove_watermark、merge
steps[].status该步结果,成功为 success
done / total去水印这一步已完成片数和总片数

上限

限制值超限
切片时长5–120 秒提交时返回 HTTP 400,业务码 1001
切片数最多 180 片任务失败,error.message 给出实际段数和总时长
总时长最长 1 小时同上
任务超时24 小时HTTP 504,业务码 3601

超限时整单失败,不计费。

接缝

每一片独立生成。合并是纯流拷贝,帧数和时长守恒。相邻两片交界处可能有轻微的亮度或纹理差异。片数越多,接缝越多。segment_second 越大,接缝越少,单片处理越长。默认 30 秒。水印在画面里位置固定时,可以配合 use_mask: true,减少背景重绘。

耗时

测试环境实测,素材 35.8 秒、60fps。耗时主要看上游排队,波动很大。默认片长为 30 秒。下表是片长 20 秒和 40 秒时的实测。

模式段数端到端
自动切片,segment_second=202约 5–6 分钟
自动切片,segment_second=401约 7 分钟
单次去水印—约 8 分钟

  • 方法:GET
  • 路径:/api/tasks/{request_id}
  • request_id:受理响应里的 meta.request_id

只能查询当前密钥自己的任务。任务不存在或不属于当前密钥时,返回 HTTP 404,业务码 1000。

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": "wm-20261104-0002"
  },
  "meta": { "request_id": "f18621b0-…", "timestamp": "…" }
}

完成判定

完成条件是 success 为 true,且 data.out_data 是非空数组。success 为 false 表示失败,看 error.code 和 error.message。

data.out_data 是成片地址数组,取第一个元素作为成品。多段自动切片时,这是合并后的一条视频;只有一段时,就是那一段的产物。

处理中 data.status 是字符串 accepted,成功结果里可能是数字 2。这是上游状态,完成与否以上面的 out_data 条件为准。

单次去水印成功

单次模式不返回 duration_ms。duration_ms 是自动切片成片的总时长。

json
{
  "success": true,
  "data": {
    "status": 2,
    "error_code": "SUCCESS",
    "out_data": ["https://images.aiaipic.win/…/output.mp4"],
    "client_request_id": "wm-20261104-0001"
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

结果里还可能带上游透传字段,例如 fee、size、uuid、task_type、workflow_name、s3_url、source_path、upstream_task_id、video_format。这些字段不稳定。程序只依赖本文档列出的字段。

字段说明
out_data成片地址数组。以这里为准
client_request_id调用方请求号
error_code成功时为 SUCCESS
status上游状态。成功示例为 2

自动切片成功

下面是 segment_second 为 20 时的一次结果。不传该字段时,默认片长是 30 秒。

json
{
  "success": true,
  "data": {
    "status": 2,
    "error_code": "SUCCESS",
    "auto_segment": true,
    "segment_second": 20,
    "segment_count": 2,
    "out_data": ["https://fs-stg.aiaipic.win/video-merge/…/output.mp4"],
    "duration_ms": 35813,
    "segments": [
      {
        "index": 0,
        "duration_ms": 20833,
        "watermark_url": "https://images.aiaipic.win/…/seg0.mp4"
      },
      {
        "index": 1,
        "duration_ms": 14983,
        "watermark_url": "https://images.aiaipic.win/…/seg1.mp4"
      }
    ],
    "steps": [
      { "name": "segment", "status": "success" },
      { "name": "remove_watermark", "status": "success", "done": 2, "total": 2 },
      { "name": "merge", "status": "success" }
    ],
    "client_request_id": "wm-20261104-0002"
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}
字段说明
out_data成片地址数组。多段时是合并后的视频,一段时是该段产物,通常都是 1 个地址
segments[].index序号,从 0 开始
segments[].watermark_url该段去水印后的地址
segments[].duration_ms该段时长(毫秒)
segment_count实际段数
segment_second本次使用的目标片长
duration_ms成片总时长(毫秒)
auto_segment本次是否走了自动切片
steps处理步骤。只有一段时没有 merge

成片和分段地址都是对象存储直链,拿到后尽快转存,不要长期依赖。

失败

json
{
  "success": false,
  "error": { "code": 3600, "message": "上游提交失败:服务暂不可用" },
  "meta": { "request_id": "…", "timestamp": "…" }
}

自动切片失败时,error.message 会带上环节,例如:

  • 视频切片失败:…
  • 上游提交失败:…(某一片提交失败)
  • 视频合并失败:…
  • 视频过长:切片后 181 段共 3620.0 秒,超过上限(180 段 / 1 小时)

失败任务不计费。重试时换一个新的 client_request_id。

请求体带了 notice_url、callback_url 或 notify_url 时,任务进入终态后,平台向该地址 POST。没有回调地址时不会 POST。

项值
方法POST
请求体与 GET /api/tasks/{request_id} 的响应 JSON 相同
成功条件回调地址返回 HTTP 2xx
重试非 2xx 或连接失败时,30 秒后重试,最多 4 次

用 meta.request_id 或 data.client_request_id 对应自己的业务单。成功时读取 data.out_data 的第一个地址。

HTTP业务码说明
4041000任务不存在,或不属于当前密钥
4001001参数错误。类型、范围、未知字段;只传了 segment_second 却没有 auto_segment;未开 auto_segment 却传了 m3u8_key_url 或 m3u8_secret;m3u8_secret 不是 32 位十六进制;加密 m3u8 未提供密钥
4131004请求实体过大
4001101请求体不是合法 JSON
4011102缺少 Authorization
5001500服务器内部错误
5031502服务暂不可用,稍后重试
5023600上游处理失败。含切片失败、合并失败、某一片提交失败、没有产物
5043601上游处理超时,任务超过 24 小时
4094003同一调用方请求号,参数不同
4004102缺少 video_url
4004107video_url 或 m3u8_key_url 不是合法的 http 或 https 链接
4015003API Key 无效
4035103账户已被禁用
4035104账户已被暂停
4035204未开通该产品
4015301Key 已过期
4015304Key 已撤销
4295705请求过于频繁
4299902配额已超出
4029903余额不足

按视频时长(秒)乘以单价,一次结算。auto_segment 不另收费,切片和合并不单独计费。失败和超时不计费。响应里不返回金额。单价见首页透明接口定价。

项值
环境https://test-star-api.aiaibase.com
测试素材https://videos.pexels.com/video-files/39750493/16953211_1080_1920_60fps.mp4(35.8 秒,1080×1920,60fps)
auto_segment=true,segment_second=202 段(约 20.8 秒 + 15.0 秒),segment_count 为 2,out_data 为合并成片
auto_segment=true,不传 segment_second默认 30 秒一片
预期耗时5–8 分钟,取决于上游排队
bash
BASE=https://test-star-api.aiaibase.com

curl -s -X POST "$BASE/api/video_remove_watermark" \
  -H "Authorization: Bearer {API Key}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://videos.pexels.com/video-files/39750493/16953211_1080_1920_60fps.mp4",
    "auto_segment": true,
    "segment_second": 30,
    "client_request_id": "demo-0001"
  }'

curl -s "$BASE/api/tasks/{request_id}" \
  -H "Authorization: Bearer {API Key}"

success 为 true 且 data.out_data 非空时,取 out_data 的第一个地址。success 为 false 时看 error.code 和 error.message。