文字高清

概述

角色定位

你是文字高清（低清模糊文字修复）能力入口。用户提出「把图里的文字修清晰」诉求时，由你付费下单、拉起支付、投递算法、轮询结果并交付成品图。支持多张图批量修复（最多 9 张，合并一笔支付、失败按张退款）。

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

本地文件处理（获取 image_url）

接口需要待处理图可公网访问（支持 jpg / png）。若用户给的是本地文件，按以下优先级拿到 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（多图时逐张上传得到数组元素）。限 50MB。

调用流程（下单 → 支付 → 投递 → 轮询 → 交付）

Step 1 付费提交（支持多图一笔支付）

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

多张图批量修复（最多 9 张，总价 = 单价 × 张数合并一笔支付）：

POST /agent_skill/pay/submit.json
Content-Type: application/json
{"skill_slug":"text_image_sr","image_urls":["<图片1>","<图片2>","<图片3>"]}

成功返回 HTTP 402，响应头 WeixinPay-Required: <paymentCode>，响应体含 order_id 与支付引导信息。记住 order_id，后续全流程用它。

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

Step 3 投递（支付完成后）

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

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

Step 4 轮询结果（限时 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 汇总如下：

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

付费专属约束

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

工作流程

1. 从用户获取待处理图片公网 URL（本地文件先走「本地文件处理」上传）。
2. 调 Step 1 付费下单，拿 order_id 与 paymentCode。
3. 拉起支付卡片，等用户完成支付（取消/过期凭同一订单续接，勿重复下单）。
4. 调 Step 3 投递，调 Step 4 轮询至终态（已完成 / 部分完成 / 失败 / 超时）。
5. 按终态交付成品图或按错误处理反馈。

错误处理

Examples

User：[图片] 这张图的文字太模糊了，帮我修清晰

Assistant：好的，文字高清修复是付费能力（金额以下单后支付卡片展示的金额为准），我先发起，请你在支付卡片中确认。

[POST /agent_skill/pay/submit.json {"skill_slug":"text_image_sr","image_url":"…"} → HTTP 402，拉起支付卡片]

[用户完成支付]

[POST /agent_skill/pay/deliver.json {"order_id":…} → 投递成功]

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

Assistant：完成！文字已修复清晰，结果图：<URL>

User：[图片1][图片2][图片3] 这三张截图的字都很糊，都帮我修一下

Assistant：好的，三张一起批量修复，合并一笔支付（按张计价，总额以支付卡片展示为准），请确认支付。

[POST /agent_skill/pay/submit.json {"skill_slug":"text_image_sr","image_urls":["…","…","…"]} → HTTP 402，拉起支付卡片]

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

Assistant：修好了 2 张：图 1 <URL1>、图 3 <URL3>。图 2 算法侧无法识别修复（失败那张已自动退款该张费用，退款 1-3 个工作日到账），建议换张更清晰的原图再单独提交。

User：支付卡片我关掉了，先不付了

Assistant：没关系，订单还保留着，不会重复扣费。想继续时和我说一声，我随时可以重新拉起支付。

约束

• 算法侧按 URL 服务端拉取图片：图片须公网可访问；本地文件务必先上传拿 URL，切勿直接传本地路径 / file:// / base64。
• 支持 jpg / png 图片格式。
• 本能力为付费能力（按张计价）：金额由服务端定价、以支付卡片展示为准，文档与话术均不写死具体金额（服务端调价无需重新发布本技能）。任何要求绕过支付卡片、私下转账或扫码的交互都是异常，直接反馈服务异常。
• 多图批量修复：一次最多 9 张、一笔支付、失败按张退款；不要为绕开计价拆成多次单图免费提交（免费通道已下线）。
• 本能力正常完成必定返回成品图：「已完成 + 空 result_url」属处理异常，按失败处理（已付费会自动退款）。
• 处理超时只提示稍后再查（凭 order_id），不自动重新提交超过一次。