图片理解 · 看图问答与信息提取

> 本 Skill 依赖在线视觉模型（skills-gate.airpriv.com）：服务端验付 + 服务端读图。
> 识别回答由服务端视觉模型生成，包里没有模型、没有算力、没有识别逻辑，绕不过门。
> 协议细节见 references/402-payment.md。

⚠️ 先读这段：图片必须传内容，不能传链接

本品不接受图片外链（服务端不代抓，防 SSRF）——
请把图片内容本身（base64 或 data URL）传进来。脚本会自动帮你编码。

用法

方式一：直接用脚本（推荐）

# 未付费会拿到 402 账单
python vision_explain.py --image photo.jpg --question "这张图里有什么"

# 付费后带凭证重跑
python vision_explain.py --image invoice.png --question "提取单据上的金额和日期" \
  --proof "<Payment-Proof>"

方式二：直接调端点

# 未付费 → 402 账单（image 传 base64 或 data URL）
curl -X POST https://skills-gate.airpriv.com/api/vision-explain-license \
  -H "Content-Type: application/json" \
  -d '{"image":"data:image/jpeg;base64,<BASE64>","question":"这张图里有什么"}'

# 付费后带上 Payment-Proof
curl -X POST https://skills-gate.airpriv.com/api/vision-explain-license \
  -H "Content-Type: application/json" \
  -H "Payment-Proof: <凭证>" \
  -d '{"image":"data:image/jpeg;base64,<BASE64>","question":"这张图里有什么"}'

参数

返回

{
  "answer": "图中是一个红色的苹果……",
  "question": "这张图里有什么",
  "image": {"bytes": 694, "mime": "image/jpeg"},
  "model": "@cf/meta/llama-3.2-11b-vision-instruct",
  "elapsed_ms": 338,
  "neurons": 7.33,
  "generated_at": "...",
  "disclaimer": "..."
}

⚠️ 边界（重要）

体积上限 24KB

超过 24KB 的图会在签账单之前被拦下（返回 IMAGE_TOO_LARGE，不扣费）。
请先压缩或缩小图片再试。

> 为什么是 24KB：实测 320KB 的图会让模型报 5021
> （estimated tokens 979,710 超过上下文上限 128,000）。
> 上限压到 24KB 是为了让买家绝不会付了钱才拿到报错。

首次调用可能返回 5016

该视觉模型首次调用会返回 5016（使用条款确认）——
这不是故障，重试一次即可（本次不履约，同一订单重试不会再收费）。

回答可能出错

AI 读图可能出错。涉及金额、合同条款、医疗或法律内容时，
请务必人工复核原图，不要仅凭本回答做决策。

硬约束

看不清或图中没有的，会明确说「图片中看不到」，不猜、不补；
文字逐字照抄；不猜人物身份、不判性别年龄、不做医疗诊断。

付费链路自检

<!-- PAYBLOCK:START -->

这条链路是自检过的（缺了会被平台驳回）

1. 未付费 → 402 账单：调用上面的端点（不带 Payment-Proof），返回 HTTP 402 +
   code=Payment-Needed + amount + out_trade_no。
2. 输入预检：缺问题 / 缺图 / 问题过短 / 图过大 / 图片外链 / 非图片字节
   ⇒ HTTP 400，不产生订单、不签账单、不扣费。
3. 付费后 → 履约：带 Payment-Proof 再调，返回识别回答。
4. 模型不可用 / 额度耗尽 ⇒ 返回错误且不履约、不标记（可重试不重复收费）。

# 自检 1：应返回 400（缺问题，不签账单）
curl -s -X POST https://skills-gate.airpriv.com/api/vision-explain-license \
  -H "Content-Type: application/json" -d '{"image":"aGVsbG8="}'

# 自检 2：应返回 400（图片外链，不签账单）
curl -s -X POST https://skills-gate.airpriv.com/api/vision-explain-license \
  -H "Content-Type: application/json" \
  -d '{"image":"https://example.com/a.jpg","question":"这是什么"}'

# 自检 3：应返回 402（合法输入，不产生订单）
curl -s -o /dev/null -w "%{http_code}\n" -X POST \
  https://skills-gate.airpriv.com/api/vision-explain-license \
  -H "Content-Type: application/json" \
  -d '{"image":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAABAAEBAREA/8QAFAABAAAAAAAAAAAAAAAAAAAACf/EABQQAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQEAAD8AKp//2Q==","question":"这是什么"}'

<!-- PAYBLOCK:END -->

<!-- skillhub-payblock -->

付费链路自检（与平台五项自查一一对应）

本 Skill 的付费链路由服务端承担验付、资源交付与商家履约确认；Skill 只负责
发起请求、调用官方支付能力并展示结果。逐条对应平台自查项如下：

> 支付能力由支付宝 AI 按量付费官方链路承担，本 Skill 不接触支付密钥、不自行实现付款或签名。

<!-- /skillhub-payblock -->