智绘图片理解

元数据

服务地址

Base URL：https://iskills.ixhlink.com

下文接口均写路径（如 /api/v1/llm/invoke），完整地址 = Base URL + 路径。

统一响应格式：

{"success": true, "code": 0, "message": "ok", "data": {}}

调用流程

vision 为同步能力，典型流程：

1. （可选）GET /api/v1/llm/models 确认模型已启用
2. POST /api/v1/llm/invoke 提交图片理解请求（messages 中含图片与文字）
3. 若返回 402：调起微信支付，成功后用相同 JSON body 重试，Header 附带 WeixinPay-Required 与 X-Payment-Id
4. 从 data.choices[0].message.content 读取模型回复文本

1. 查询模型（可选）

GET /api/v1/llm/models
Accept: application/json

确认返回的 items 中包含：

{"model": "ixhlink-skills-image-explain", "capability": "vision"}

2. 提交图片理解

POST /api/v1/llm/invoke
Content-Type: application/json

请求体（URL 图片）：

{
  "capability": "vision",
  "model": "ixhlink-skills-image-explain",
  "payload": {
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "请详细描述这张图片的内容、主体、场景与氛围"},
          {
            "type": "image_url",
            "image_url": {"url": "https://example.com/photo.jpg"}
          }
        ]
      }
    ]
  }
}

请求体（Base64 图片）：

{
  "capability": "vision",
  "model": "ixhlink-skills-image-explain",
  "payload": {
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "图中有什么文字？请逐条列出"},
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,"
            }
          }
        ]
      }
    ]
  }
}

payload 字段：

简写（仅文字问题时）： 若只传 prompt 且无图片，服务端会转为单轮 messages：

{
  "capability": "vision",
  "model": "ixhlink-skills-image-explain",
  "payload": {
    "prompt": "你好"
  }
}

带图片时请使用上文 messages + image_url 格式。

多图理解示例：

{
  "capability": "vision",
  "model": "ixhlink-skills-image-explain",
  "payload": {
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "对比这两张图的差异"},
          {"type": "image_url", "image_url": {"url": "https://example.com/a.jpg"}},
          {"type": "image_url", "image_url": {"url": "https://example.com/b.jpg"}}
        ]
      }
    ]
  }
}

调用成功响应（同步）：

{
  "success": true,
  "code": 0,
  "message": "调用成功",
  "data": {
    "id": "chatcmpl-xxx",
    "object": "chat.completion",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "这是一张……"
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 1200,
      "completion_tokens": 180,
      "total_tokens": 1380
    },
    "_billing": {
      "call_log_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

模型回复文本在 data.choices[0].message.content；排查日志可用 data._billing.call_log_id。

付费说明

当 amount_fen > 0 且未完成支付时，首次 POST /api/v1/llm/invoke 会返回 HTTP 402，响应中携带：

• Header：WeixinPay-Required: 、X-Payment-Id:
• Body：WeixinPay 对象（含 payment_id、prompt 等）

客户端流程（Agent / MCP / Web）：

首次 invoke → 402 → weixinpay_pay(payment_code) → 支付成功后重试 invoke

「原样重试」的含义：

• JSON body 不变：model、capability、payload 必须与首次请求完全一致
• 订单参数单独带上：将 402 中的 payment_code、payment_id 通过 Header 传入（推荐），或写入 body 的 WeixinPay；勿改 payload 业务字段来传订单号

重试请求示例：

POST /api/v1/llm/invoke
Content-Type: application/json
WeixinPay-Required: 
X-Payment-Id: 

{"model":"ixhlink-skills-image-explain","capability":"vision","payload":{...}}

amount_fen = 0 时可跳过支付，直接调用。每笔订单按次消费，使用后不可复用。

错误处理

上游失败时查看响应 message 与 _billing.call_log_id 对应后台调用日志。