视频去水印API接入指南：异步任务提交、轮询与下载

视频去水印不是普通文件上传：提交后需要等待AI处理并查询结果。轻语 removeWatermarkV3 采用提交与查询分离的异步模式，适合素材清理、字幕处理和内容生产工作流。

一、异步流程总览

1. 以multipart/form-data上传视频并提交任务。
2. 保存响应中的 taskId，关联业务记录。
3. 按固定间隔调用status接口，读取 progress。
4. 状态为completed时取得 videoUrl，失败时展示可重试原因。

二、提交任务

curl -X POST 'https://5555api.com/data/api/removeWatermarkV3' \
  -F 'apikey=YOUR_APIKEY' \
  -F 'file=@product-video.mp4' \
  -F 'mode=quality' \
  -F 'target=watermark' \
  -F 'region=top-right'

const form = new FormData();
form.append('apikey', process.env.QINGYU_API_KEY);
form.append('file', videoFile);
form.append('mode', 'quality');
form.append('target', 'auto');
const submitted = await fetch(
  'https://5555api.com/data/api/removeWatermarkV3',
  { method: 'POST', body: form }
).then(response => response.json());
if (submitted.code !== 200) throw new Error(submitted.msg || '提交失败');
const taskId = submitted.data.taskId;

三、轮询进度并下载结果

async function waitForVideo(taskId) {
  for (let attempt = 0; attempt < 100; attempt += 1) {
    await new Promise(resolve => setTimeout(resolve, 3000));
    const query = new URLSearchParams({
      taskId,
      apikey: process.env.QINGYU_API_KEY
    });
    const status = await fetch(
      'https://5555api.com/data/api/removeWatermarkV3/status?' + query
    ).then(response => response.json());
    if (status.code !== 200) throw new Error(status.msg || '查询失败');
    if (status.data.status === 'completed') return status.data.videoUrl;
    if (status.data.status === 'failed') throw new Error('视频处理失败');
  }
  throw new Error('等待处理超时');
}

四、任务系统的工程注意点

1. 不要让浏览器直接持有API Key，前端轮询自己的业务任务接口。
2. 任务记录至少保存业务ID、taskId、原文件ID、状态和结果地址。
3. 轮询间隔不宜过短；同时设置最大次数，避免页面长期占用连接。
4. 完成后及时转存重要视频，临时结果地址不应成为唯一备份。

五、如何降低误处理

水印位置固定时使用 region，文字水印可配合 ocr=rapidocr，检测密度通过 gap 调整。先在视频去水印在线工具中验证目标区域，再把相同参数写入API任务。

六、相关文档

参数枚举、响应字段和Python示例请查看视频去水印API文档。如果只是处理少量素材，也可以直接使用在线去水印工具。

常见问题

视频去水印API为什么要轮询？

视频处理耗时受时长、分辨率和检测区域影响，接口采用异步任务返回taskId，客户端查询status接口获取进度和最终videoUrl。

taskId应该保存在哪里？

服务端应把taskId和业务订单、原始文件ID关联保存，客户端只拿到业务任务标识，避免刷新页面后丢失处理状态。

如何选择target和region？

target可选auto、subtitle、timestamp、watermark和logo；已知目标类型时显式指定，region可限制处理区域以减少误检和处理时间。

结语

视频去水印API的核心是可靠的异步任务链路：提交可重试、状态可追踪、结果可下载。把taskId持久化并加上最大等待时间，才能让批量素材处理真正可运营。