视频去水印接口文档
提交视频地址去掉画面水印。短视频默认同一次处理;长视频可自动切片、逐片去水印再合并。按时长计费,完成后查询或回调。
提交一个视频地址,去掉画面水印。本接口是异步的:提交后拿到任务号,再查询结果;请求里带了回调地址时,任务结束会再 POST 同一份结果。
同一个接口有两种模式:
| 模式 | 开启方式 | 行为 | 适用 |
|---|---|---|---|
| 单次去水印(默认) | 不传 auto_segment,或传 false | 整段视频一次送上游去水印 | 短视频。默认只处理前 650 帧 |
| 自动切片 | auto_segment: true | 先按 segment_second 切片(默认 30 秒),逐片去水印,再合并成片。video_url 可以是 m3u8 | 长视频。最多 180 片,视频最长 1 小时 |
自动切片在服务端编排。调用方仍然是提交一次、拿一个成片,不必再调视频切片与合并。
| 方法与路径 | 产品编码 | 说明 |
|---|---|---|
POST /api/video_remove_watermark | video_remove_watermark | 提交视频去水印任务 |
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请求体为 JSON,Content-Type: application/json。认证只使用请求头:
Authorization: Bearer {API Key}{API Key} 由平台签发,只能放在服务端。浏览器或前端仓库里不要出现 Key,由自己的后端转发。测试 Key 向平台单独申请,不要复用线上 Key。
水印位置固定、只修补指定区域并保持源分辨率和帧率时,使用视频去水印快速版。短视频用默认单次模式。长视频打开
auto_segment。需要单独拿到分段或自行合并时,使用视频切片与合并。需要去掉图片水印时,使用图片去水印。需要超清放大时,使用视频超清放大。需要从音轨生成字幕时,使用音频字幕。需要自动选择字幕轨、画面字幕或语音识别时,使用智能字幕。若只需翻译已经分好条的字幕,请使用字幕翻译。
所有响应都是同一结构。业务结果看 success 和 error.code。HTTP 状态与业务码的对应关系见错误码。
| 字段 | 类型 | 说明 |
|---|---|---|
success | bool | 受理成功、处理中、处理成功为 true;失败为 false |
data | object | 成功或处理中的业务数据。失败时不返回 |
error | object | 失败时的错误。含 code、message |
meta.request_id | string | 平台任务号。查询和排查都用这个值 |
meta.timestamp | string | 响应时间,例如 2026-11-04T13:26:55+08:00 |
{
"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 | 否 | bool | false | 是否自动切片。见下方自动切片 |
segment_second | 否 | int | 30 | 切片目标时长(秒),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 | 否 | bool | false | 是否取消上游 650 帧截断。auto_segment 为 true 时服务端强制开启 |
use_mask | 否 | bool | false | 遮罩预处理。水印位置固定时画面更干净,但可能留下浅色糊斑,建议对比后再定 |
is_encrypt | 否 | bool | false | 是否加密输出 |
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.status | string | 固定为 accepted |
data.client_request_id | string | 调用方请求号 |
meta.request_id | string | 平台任务号 |
{
"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"
}
}单次去水印示例
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"
}'自动切片示例
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,至少传一个。
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 时,服务端按下面的顺序处理:
提交 → 切片 → 每片去水印 → 合并 → 完成| 场景 | 传参 |
|---|---|
| 默认 30 秒一片 | auto_segment: true |
| 指定片长 | auto_segment: true,segment_second: 40 |
| 未加密 m3u8 | auto_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 就是这条链路,可以直接展示:
"steps": [
{ "name": "segment", "status": "success" },
{ "name": "remove_watermark", "status": "success", "done": 2, "total": 2 },
{ "name": "merge", "status": "success" }
]只有 1 片时没有 merge:
"steps": [
{ "name": "segment", "status": "success" },
{ "name": "remove_watermark", "status": "success", "done": 1, "total": 1 }
]| 字段 | 说明 |
|---|---|
steps[].name | segment、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=20 | 2 | 约 5–6 分钟 |
自动切片,segment_second=40 | 1 | 约 7 分钟 |
| 单次去水印 | — | 约 8 分钟 |
- 方法:
GET - 路径:
/api/tasks/{request_id} request_id:受理响应里的meta.request_id
只能查询当前密钥自己的任务。任务不存在或不属于当前密钥时,返回 HTTP 404,业务码 1000。
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": "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 是自动切片成片的总时长。
{
"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 秒。
{
"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 |
成片和分段地址都是对象存储直链,拿到后尽快转存,不要长期依赖。
失败
{
"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 | 业务码 | 说明 |
|---|---|---|
| 404 | 1000 | 任务不存在,或不属于当前密钥 |
| 400 | 1001 | 参数错误。类型、范围、未知字段;只传了 segment_second 却没有 auto_segment;未开 auto_segment 却传了 m3u8_key_url 或 m3u8_secret;m3u8_secret 不是 32 位十六进制;加密 m3u8 未提供密钥 |
| 413 | 1004 | 请求实体过大 |
| 400 | 1101 | 请求体不是合法 JSON |
| 401 | 1102 | 缺少 Authorization |
| 500 | 1500 | 服务器内部错误 |
| 503 | 1502 | 服务暂不可用,稍后重试 |
| 502 | 3600 | 上游处理失败。含切片失败、合并失败、某一片提交失败、没有产物 |
| 504 | 3601 | 上游处理超时,任务超过 24 小时 |
| 409 | 4003 | 同一调用方请求号,参数不同 |
| 400 | 4102 | 缺少 video_url |
| 400 | 4107 | video_url 或 m3u8_key_url 不是合法的 http 或 https 链接 |
| 401 | 5003 | API Key 无效 |
| 403 | 5103 | 账户已被禁用 |
| 403 | 5104 | 账户已被暂停 |
| 403 | 5204 | 未开通该产品 |
| 401 | 5301 | Key 已过期 |
| 401 | 5304 | Key 已撤销 |
| 429 | 5705 | 请求过于频繁 |
| 429 | 9902 | 配额已超出 |
| 402 | 9903 | 余额不足 |
按视频时长(秒)乘以单价,一次结算。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=20 | 2 段(约 20.8 秒 + 15.0 秒),segment_count 为 2,out_data 为合并成片 |
auto_segment=true,不传 segment_second | 默认 30 秒一片 |
| 预期耗时 | 5–8 分钟,取决于上游排队 |
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。