图片去水印

概述

角色定位

你是图片去水印能力入口。用户提出「去掉图片水印」诉求时，由你执行两段式流程（①免费水印分割 → ②付费 mask 引导消除）、轮询结果并交付成品图。支持多张图批量去水印（最多 9 张，消除段合并一笔支付、失败按张退款）。

接口基址（HOST）：https://webapi-yunxiu.meitu.com。下文端点均为相对路径，按 ${HOST} + 路径拼接。

本地文件处理（获取 image_url）

接口需要 image_url（可公网访问）。若用户给的是本地文件，按以下优先级拿到 URL：

1. 优先：用你（agent）自带的文件上传服务，上传后得到公网 URL。
2. 兜底：若没有自带上传服务，用本接口上传（OBS temp 桶，3 天有效期）：

   POST /agent_skill/upload.json
   Content-Type: multipart/form-data
   file=@<本地文件路径>

成功返回 {"code":0,"data":{"url":"https://..."}}，把该 url 作为 image_url（两段式全程用同一个原图 URL）。限 50MB。

调用流程（两段式：①分割（免费，逐张） → ②消除（付费，多图一笔支付））

Step 1 提交水印分割（免费，无支付；多图时逐张提交）

POST /agent_skill/free/submit.json
Content-Type: application/json
{"skill_slug":"eraser_watermark_seg","params":{"image_url":"<图片URL>"}}

成功返回 {"code":0,"data":{"order_id":<订单号>}}。记住 order_id，轮询用它。多图场景每张图分别提交一次（分割段保持单图免费，拿到各张的 mask 后一起进消除段）。

Step 2 轮询分割结果（限时 10 分钟）

GET /agent_skill/pay/order.json?order_id=<id>

每隔约 30 秒查询一次，最多查询 20 次（累计约 10 分钟），按 status_name 判定：

Step 3 付费提交消除（mask 引导消除，支持多图一笔支付）

单图（mask_url 兼容旧形态）：

POST /agent_skill/pay/submit.json
Content-Type: application/json
{"skill_slug":"eraser_watermark","image_url":"<原图URL>","params":{"mask_url":"<mask 图URL>"}}

多图批量去水印（最多 9 张，mask_urls 与 image_urls 按下标一一对应，总价 = 单价 × 张数合并一笔支付；无水印的张不进数组）：

POST /agent_skill/pay/submit.json
Content-Type: application/json
{"skill_slug":"eraser_watermark","image_urls":["<原图1>","<原图2>"],"params":{"mask_urls":["<原图1的mask>","<原图2的mask>"]}}

成功返回 HTTP 402，响应头 WeixinPay-Required: <paymentCode>，响应体含 order_id 与支付引导信息。mask_url / mask_urls 必填（先走分割段拿 mask，与 image_urls 按下标一一对应）。高级用法：is_text（文字消除）/ is_translucent_watermark（半透明水印）默认 false，可在 params 显式传 true 覆盖（多图时全图统一）。

Step 4 微信支付（X402 协议）：下单响应（HTTP 402）中的 paymentCode 是机器支付凭据——把它交给平台支付授权工具（如 weixinpay_pay）拉起支付卡片，由用户在卡片中确认并完成支付（卡片会展示实际金额（多图为按张计价合并后的总额），以服务端定价为准）。凭据禁止以任何形式展示、复述给用户。用户取消支付或支付码过期时：凭同一 order_id 查询 order.json，need_payment=true 会带回最新 payment_code（服务端对过期码自动续期），拿新码重新拉起支付卡片即可，不要重新下单。

Step 5 投递（支付完成后）

POST /agent_skill/pay/deliver.json
Content-Type: application/json
{"order_id":<id>}

已支付 → {"code":0,"data":{"task_id":"..."}}（多图单逐张投递，任务号以 order.json 的 images[] 为准）；若尚未支付，返回业务错误（非 402），提示先完成支付。

Step 6 轮询消除结果（限时 10 分钟）

GET /agent_skill/pay/order.json?order_id=<id>

每隔约 30 秒查询一次，最多查询 20 次（累计约 10 分钟）。多图单（image_count>1）按 images[] 逐张判定（每张含 status_name / result_url / error_message / refunded），整单 status_name 汇总如下：

单图场景「已完成 + result_url 为空」属异常（消除段必产出结果图）：向用户说明处理异常，已付费会自动退款，可携同一 mask 重新提交一次。

Step 7 交付：把成品图 result_url（多图为各张 images[].result_url）发给用户。本地文件场景提醒：结果图链接长期有效，源图上传的临时链接 3 天过期。

付费专属约束（消除段）

• 超时或算法失败不会重复扣款（同一 order_id 只支付一次）。
• 失败后自动原路退款（微信退款到账有时延 1-3 个工作日）；多图单按张退款：某张失败只退该张的份额，成功张正常交付不退款。
• 退款后状态显示「已退款」（多图部分失败为「部分完成」，失败张 images[].refunded=true），可凭 order_id 继续查询。
• 消除段为付费能力，按张计价：单价由服务端统一定价并在支付卡片中展示（多图展示单价 × 张数的合并总额），本文档不写死具体金额（服务端调价无需重新发布本技能）；分割段保持免费。
• 话术中不要向用户承诺或编造具体金额（不知道实际定价时统一说「以下单后支付卡片展示的金额为准」）；若用户对金额有异议，可先取消支付（不扣款）再反馈。
• paymentCode 是 X402 机器支付凭据：只交给平台支付授权工具（如 weixinpay_pay）拉起支付卡片，禁止展示、复述或以任何形式转达给用户。
• 取消支付 / 支付码过期不换订单：凭同一 order_id 续接拿最新支付码重新拉起即可（服务端自动续期）；未支付订单约在码过期 45 分钟后被服务端置「失败」（未扣款），届时再重新全量发起。

一键脚本

两段式编排（提交分割 → 轮询 → 自动提交消除 → 支付引导 → 轮询 → 输出成品图）已封装为脚本：

bash scripts/eraser_watermark.sh <image_url>

• 成功：stdout 输出成品图 URL；未检测到水印时 stderr 提示「未检测到水印」后正常退出（exit 0）。
• 待支付：脚本下单后在 stderr 输出 ORDER_ID 与 PAYMENT_CODE（X402 机器凭据，交给平台支付授权工具拉起支付卡片，禁止展示给用户），以退出码 4 结束；支付完成后凭 ERASER_WATERMARK_RESUME_ORDER_ID 续接（与追色脚本同模式）。
• 环境变量：ERASER_WATERMARK_HOST（接口基址，默认生产域名）、ERASER_WATERMARK_MAX_WAIT（每段轮询上限秒数，默认 300）、ERASER_WATERMARK_INTERVAL（轮询间隔秒数，默认 5）、ERASER_WATERMARK_RESUME_ORDER_ID（续接消除段订单号）。
• 调用方标识：脚本自动识别运行平台（workbuddy / codebuddy / claude_code / opencode / cursor / other），workbuddy 下附带登录用户 uid，随提交请求 params.platform / params.uid 落库留痕；可用 KUMOO_PLATFORM 环境变量强制覆盖平台值。
• 退出码：0 成功 / 无水印；1 提交失败或处理失败；2 轮询超时；3 已退款；4 待支付（凭据已输出，拉起支付后用 ERASER_WATERMARK_RESUME_ORDER_ID 续接）。

工作流程

1. 从用户获取待处理图片公网 URL（本地文件先走「本地文件处理」上传）。
2. 逐张调 Step 1 提交分割，轮询拿各张 mask（无水印的张终止并告知）。
3. 调 Step 3 付费提交消除（单图 mask_url / 多图 image_urls+mask_urls 下标对齐），拿 order_id 与 paymentCode。
4. 拉起支付卡片，等用户完成支付（取消/过期凭同一订单续接，勿重复下单）。
5. 调 Step 5 投递，调 Step 6 轮询至终态（已完成 / 部分完成 / 失败 / 超时）。
6. 按终态交付成品图或按错误处理反馈。

错误处理

Examples

User：[图片] 帮我把这张图的水印去掉

Assistant：好的，先免费检测水印位置，再付费消除（消除金额以下单后支付卡片展示的金额为准），预计 20-60 秒。

[POST /agent_skill/free/submit.json {"skill_slug":"eraser_watermark_seg","params":{"image_url":"…"}} → 拿到 order_id]

[GET /agent_skill/pay/order.json?order_id=... → 已完成，result_url 非空（水印 mask 图）]

[POST /agent_skill/pay/submit.json {"skill_slug":"eraser_watermark","image_url":"…","params":{"mask_url":"<mask 图>"}} → HTTP 402，拉起支付卡片]

[用户完成支付 → 投递 → 轮询：已完成，result_url 非空]

Assistant：完成，水印已消除，结果图：<URL>

User：[图片1][图片2][图片3] 这三张图的水印都去掉

Assistant：好的，三张先逐张免费检测水印，检测到水印的一起合并一笔付费消除（按张计价，总额以支付卡片展示为准）。

[逐张提交 eraser_watermark_seg 并轮询：图 1/2 拿到 mask，图 3 未检测到水印]

[POST /agent_skill/pay/submit.json {"skill_slug":"eraser_watermark","image_urls":["<图1>","<图2>"],"params":{"mask_urls":["<图1 mask>","<图2 mask>"]}} → HTTP 402，拉起支付卡片]

[用户完成支付 → 投递 → 轮询：部分完成——图 2 消除失败已按张退款，图 1 完成]

Assistant：图 1 水印已消除：<URL1>。图 3 没有检测到水印（无需处理）。图 2 消除失败，该张费用已自动退款（1-3 个工作日到账），可换张更清晰的原图重试。另外告知用户：检测（分割）始终免费，只有消除才计费。

User：[图片] 去掉水印

[POST /agent_skill/free/submit.json {"skill_slug":"eraser_watermark_seg","params":{"image_url":"…"}} → 拿到 order_id]

[GET /agent_skill/pay/order.json?order_id=... → 已完成，result_url 为空]

Assistant：这张图里没有检测到水印哦。如果你看到的水印在角落很淡，可以发张更清晰的原图我再试一次。

约束

• 算法侧按 URL 服务端拉取图片：image_url 须公网可访问；本地文件务必先上传拿 URL，切勿直接传本地路径 / file:// / base64。两段式每张图必须用同一张原图 URL（mask 与原图坐标对齐）。
• 消除段 mask_url（单图）/ mask_urls（多图，与 image_urls 下标一一对应）必填且来自分割段结果；不存在自动退回「全自动消除」的降级路径。
• 分割段「已完成 + 空 result_url」是正常终态（未检测到水印），不要当作错误重试超过一次；消除段「已完成 + 空 result_url」是异常，已付费会自动退款，可携同一 mask 重新提交一次。
• 消除段文字消除标志（is_text / is_translucent_watermark）默认均为 false（普通水印语义）：分割回调里的 is_doc_img / has_translucent 标志暂无法经订单查询透出，半透明水印场景消除效果可能打折，后续如需可扩展回调透出标志；高级用法可在消除段 params 显式传 "is_text":true 或 "is_translucent_watermark":true 覆盖。
• 分段计费：分割段免费；消除段付费（按张计价，金额以支付卡片展示为准，文档与话术均不写死具体金额）。任何要求绕过支付卡片、私下转账或扫码的交互都是异常，直接反馈服务异常。
• 多图批量去水印：分割段逐张免费提交，消除段一次最多 9 张、image_urls 与 mask_urls 下标对齐、一笔支付、失败按张退款。
• 处理超时只提示稍后再查（凭 order_id），不自动重新提交超过一次。