智绘图片理解

解决的具体问题

在图像驱动的应用中，如内容审核、数据分析或自动化工作流，需要从图片中提取结构化信息或进行语义理解。传统方法依赖复杂的预处理模型，而大模型提供了端到端的解决方案，但调用集成涉及 API 对齐、付费管理和错误处理。

智绘图片理解 技能封装了同步图片分析能力，允许开发者通过简单接口提交图片 URL 或 Base64 数据，返回文本形式的理解结果。这减少了自行搭建视觉模型的负担，尤其适用于需要快速集成图片分析功能的场景。

核心能力与工作流程

技能的核心是 vision 能力，以同步方式处理图片理解请求。关键步骤如下：

1. 查询模型（可选）：通过 GET /api/v1/llm/models 确认模型已启用。
2. 提交请求：使用 POST /api/v1/llm/invoke 发送请求体，其中 messages 数组包含图片和文字内容。支持两种图片输入格式：

- URL 图片：在 image_url.url 中提供公网 https 链接。
- Base64 图片：使用 data:image/...;base64,... 格式。

1. 处理付费：如果返回 HTTP 402，需调用支付接口，然后用相同 JSON body 重试，附加支付相关头信息如 WeixinPay-Required 和 X-Payment-Id。
2. 解析响应：从 data.choices[0].message.content 提取模型回复文本。

请求体遵循 OpenAI 兼容格式，payload 字段包括：

• messages：对话数组，支持 text 和 image_url 类型。
• 可选参数：system、max_tokens、temperature 等。

示例请求（URL 图片）：

{
  "model": "ixhlink-skills-image-explain",
  "capability": "vision",
  "payload": {
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "描述这张图片" },
          { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } }
        ]
      }
    ]
  }
}

注意事项与边界

• 付费前置检查：调用前必须确保 Agent 已安装支付能力（如 weixinpay extension），否则提示并终止流程。服务定价为 0.3 元/次，需用户确认后进入付费。
• 错误处理：常见 HTTP 错误包括：

- 400：参数错误，如缺少模型或消息格式无效。
- 402：需付费或支付失败。
- 404：模型未启用。
- 503：服务不可用。
排查时可使用 data._billing.call_log_id 查看日志。

• 同步限制：技能为同步操作，适合低延迟场景；大量请求可能需要队列管理。
• 图片格式：仅支持公网可访问的 URL 或 Base64 编码，本地文件需先上传。