视频去水印AI工具 | 去水印 | 去除水印 | 视频水印移除 | 青虎AI
qhkit video-edit 的 remove_watermark 专用接口：一次最多 10 条视频批量去水印。只处理确实带水印的素材——输入无水印视频会被算法判为无需处理并直接失败（见「失败路径」）。
何时触发
- 「这条/这批视频去下水印」「把角标 logo 去掉」
- 「用 AI 工具把视频水印抹掉」「去水印 AI 工具处理一下这批素材」
使用配方
# 提交去水印任务（urls 1–10 个，本地路径或公网 URL）
qhkit video-edit generate '{"action":"remove_watermark","urls":["./视频1.mp4","./视频2.mp4"]}'
# 提交后拿到 videoTaskId，重复查状态直到终态
qhkit video-edit status '{"videoTaskId":"VIDEO_EDIT:xxxxx"}'
- 提交成功返回
{"ok":true,"stage":"pending","videoTaskId":"VIDEO_EDIT:<uuid>","action":"remove_watermark","modelLabel":"视频去水印"}，记下videoTaskId。 urls一次 1–10 个，本地文件路径或公网 URL 都收（本地文件 CLI 自动上传）；少于 1 个会被拒：需要至少 1 个视频（urls：公网 URL 或本地文件路径）。action必须是remove_watermark（本技能只做去水印）；写错会被拒并列出合法值：不支持的 action：xxx。可选：remove_watermark / remove_subtitle / video_super_resolve。- 参数写进文件更稳：
qhkit video-edit generate @params.json。 video-edit不支持 estimate，本技能没有事前报价能力——不要调qhkit video estimate（那是 AI 视频生成命令，需要modelLabel，与去水印无关，调用会报「请指定模型」）。费用只能按实际扣费为准，或参考下方「计费」一节。
轮询与失败路径（关键）
generate 只提交，必须重复 status 直到终态。三种终态都要处理，不要只等 done：
| status 返回 | 含义 | 该怎么做 |
|---|---|---|
{"ok":true,"stage":"status","status":"pending"} |
排队中 | 继续轮询 |
{"ok":true,"stage":"status","status":"processing"} |
处理中 | 继续轮询 |
{"ok":true,"stage":"status","status":"done"} |
完成 | 取产物 URL，见「交付」 |
{"ok":false,"stage":"poll","message":"NO_WATERMARK_FOUND: ..."} |
未检测到水印，任务失败 | 见下方说明 |
{"ok":false,"stage":"poll","message":"全部失败: ..."} |
批量时每条都失败 | 逐条转述失败原因 |
NO_WATERMARK_FOUND 是最常见的失败（务必主动讲清）
当视频本身没有水印（或水印太淡、算法没识别出来）时，任务不会成功，而是直接失败：
{"ok":false,"stage":"poll","message":"NO_WATERMARK_FOUND: 未检测到水印，算法与豆包盲测均未发现水印","details":{...}}
这不是技能坏了，是它对"无需处理"素材的正常反应（算法与豆包盲测双重确认后才判定）。遇到时应当：
1. 如实告诉用户「这条素材未检测到水印，无需处理，任务已终止」；
2. 不要重试轰炸——同一素材重试结果一样，只会白跑；
3. 若用户确信有水印（比如是无痕叠加的淡色 logo），说明属于算法未识别的边界情况，建议换更明显的水印素材或改用其他处理方式，不要承诺一定成功；
4. 批量时若只有部分失败，按「批量结果」逐条汇报，成功的照常交付。
提交前先判断素材是否有水印：用户如果只是说"处理一下这批视频"却没提水印，先问清是不是要去水印；对明显无下水印可能的素材（自家新拍的原始素材），提前说明这个技能不适用。
环境自举（缺什么装什么，不要因环境缺失放弃任务）
本技能依赖 qhkit 命令（npm 包 @iqinghu/qhkit），可完全独立安装。按顺序检测，缺失就地补齐：
- 有 qhkit 吗？
qhkit config show能跑通即就绪，跳到第 4 步。 - 没有 qhkit 但有 node/npm（OpenClaw/Hermes 机器部署流程保证自带 Node 22+）→ 全局安装（推荐）：
bash
npm i -g @iqinghu/qhkit
默认走 npm 官方源；官方源访问慢或超时（国内网络常见）时，再加镜像参数 --registry=https://registry.npmmirror.com（阿里维护的 npm 官方镜像，仅作网络兜底）。仅当全局安装因权限失败且无法提权时，才退而用 npx @iqinghu/qhkit <命令> ...（npx 必须写包全名）。
3. 连 node 都没有（要求 Node ≥ 18）：先装 Node 再回到第 2 步。
bash
# Linux 二进制安装（装到用户目录，无需 root；先校验官方 SHA256 再解包）：
cd /tmp && curl -fsSLO https://nodejs.org/dist/v22.22.3/node-v22.22.3-linux-x64.tar.xz
cd /tmp && curl -fsSL https://nodejs.org/dist/v22.22.3/SHASUMS256.txt | grep ' node-v22.22.3-linux-x64.tar.xz$' | sha256sum -c -
mkdir -p "$HOME/.local/lib" && tar -xJf /tmp/node-v22.22.3-linux-x64.tar.xz -C "$HOME/.local/lib"
export PATH="$HOME/.local/lib/node-v22.22.3-linux-x64/bin:$PATH"
校验行输出 OK 才继续；校验失败就删掉重下，绝不解包未通过校验的文件。nodejs.org 访问不通时，把两个下载 URL 的前缀 https://nodejs.org/dist 整体换成镜像 https://registry.npmmirror.com/-/binary/node（目录结构相同，SHASUMS256.txt 也有镜像，校验步骤不变）。export PATH 只对当前 shell 生效，跨命令调用时每个新 shell 都要先执行这行（或追加进 ~/.bashrc）。macOS 用 brew install node；Windows 用 winget/官网安装包。arm64 机器把 x64 换成 arm64。
4. 密钥：无密钥时（命令返回 stage:"config"），执行 qhkit config set --token <密钥> --env prod（密钥让用户打开 https://www.iqinghu.com/workbench/login?type=1&urlCode=1791941828223 注册/登录后，从 https://www.iqinghu.com/workbench/dashboard/api-keys?urlCode=1791941828223 获取），或设环境变量 QHKIT_TOKEN。
5. 自检：qhkit config show 输出脱敏配置即全部就绪。
升级：出现以下任一信号，先升级再重试原命令——命令返回 {"ok":false,"stage":"version",...}（版本门禁，message 里就是升级命令，照做即可）；stderr 提示有新版本；options 返回 catalogNotice 且用户恰好要用那个新模型；报「模式在线上已下架或配置变更，请升级 qhkit」。
npm i -g @iqinghu/qhkit@latest
官方源慢或超时时同样加 --registry=https://registry.npmmirror.com。
安装/配置失败时把具体报错告诉用户（常见：无写权限 → 提示用户提权或改用 npx；无网络 → 让用户处理网络）。
调用契约
- 形式：
qhkit <命令> <action> '<json>'，或qhkit <命令> <action> @params.json（参数写进文件，避免 shell 转义问题，推荐）。 - stdout 恒为一行 JSON；失败为
{"ok":false,"stage":"...","message":"..."}且退出码 1，把 message 原样转告用户。stderr 可能出现提示行，不是错误。 - 图片/视频参数直接填本地文件路径（CLI 自动上传换取 URL），素材已在公网时填 http(s) URL 也可。
- 标签类参数（
modelLabel、sizePreset、themeLabel等）必须与options返回的候选值逐字一致，不要自造或翻译；拿不准先调options。
计费、轮询与交付
- 计费：
video-edit不支持 estimate，拿不到事前精确报价。需要给用户费用预期时，用本会话内同一action实测到的实扣值说明（generate返回里的credits字段），没实测过就说「以实际扣费为准」，不要编数字。 - 轮询：
generate只提交，立即返回videoTaskId；重复调status直到终态，间隔 30–60 秒。视频任务最长可达 40 分钟，提交后立即告知任务 ID 和耗时预期，不要提前放弃；任务不可取消，ID 要保留。status的参数既可用videoTaskId（VIDEO_EDIT:<uuid>），也可用dociD；两个都不给会报status 需要 videoTaskId（VIDEO_EDIT:{dociD}）或 dociD。 - 交付：成功后产物 URL 在
details.data.outputs（或 status 返回的videos/primaryVideo）里，按当前环境的媒体交付约定发给用户；产物必须和「完成」写在同一轮回复。 - 失败：转述 CLI 的 message（已是面向用户的中文），常见三类——
NO_WATERMARK_FOUND（未检测到水印，见「失败路径」）、积分不足、内容审核未通过。不要重试轰炸。
批量结果
一次传多条视频时，服务端会拆成 _sub1/_sub2… 子任务分别处理，按子任务粒度汇报：
- 全部成功 → 返回
status:"done"，产物里含各条视频 URL。 - 部分失败 → 成功的照常交付，失败的单独列出并附原因。
- 全部失败 →
message形如全部失败: <id>_sub1_xxx: NO_WATERMARK_FOUND: ...; <id>_sub2_xxx: NO_WATERMARK_FOUND: ...，逐条转述，不要只回一句"失败了"。
不要把批量失败笼统归因为"技能问题"——多数是素材本身无水印。
能力边界
- 本技能只做视频去水印（
remove_watermark）。去字幕走同一个video-edit命令的remove_subtitle；视频画质提升走video_super_resolve；图片去水印走图片处理路径（qhkit image自定义生图，用提示词描述要去除的元素）。 - 去除他人版权视频的水印用于商用有侵权风险，适时提醒用户仅处理自有素材。
- 无水印素材会被判
NO_WATERMARK_FOUND而失败，这不是故障，事前确认素材确实带水印。
