视觉输入与图片分析

Scope & Evidence

协议可用不等于模型具备视觉能力

端点标签只说明模型可以使用某种请求协议。openai、anthropic 或 gemini 本身都不能证明具体模型支持图片输入。

Protocol Map

模型端点标签决定消息外形

同一模型若显示多个端点标签，也应分别验证各协议；不能把一种协议下的视觉成功自动推广到另一种协议。

Image Preparation

确认 MIME、尺寸与传输方式

import base64
from pathlib import Path

image_bytes = Path("example.jpg").read_bytes()
base64_image = base64.b64encode(image_bytes).decode("ascii")
print("编码字符数：", len(base64_image))

OpenAI Compatible

使用 image_url 内容块

OpenAI 兼容视觉消息把文字和图片放在同一个用户消息的 content 数组中。即使传入 Base64，也仍然放进 image_url.url，并使用 Data URL 前缀。

curl https://api.muxllm.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "描述图片中的主体，并指出不确定之处。"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/non-sensitive-image.jpg"
            }
          }
        ]
      }
    ]
  }'

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "读取图片中清晰可见的标题；无法确认时不要猜测。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "data:image/jpeg;base64,BASE64_IMAGE_DATA"
      }
    }
  ]
}

部分实现支持 detail 等图片参数，但其取值、费用和效果可能因模型而异。首次验证不要添加未确认的可选字段。

Anthropic Native

使用 image 与 source 内容块

Claude 原生 Messages 请求的根地址不额外加 /v1，完整路径仍为 /v1/messages。图片块和文字块位于用户消息的 content 数组内。

curl https://api.muxllm.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/jpeg",
              "data": "BASE64_IMAGE_DATA"
            }
          },
          {
            "type": "text",
            "text": "列出图片中的可见对象，并区分观察与推断。"
          }
        ]
      }
    ]
  }'

Gemini Native

使用 inline_data 内容块

Gemini 原生请求把模型名放在路径中。请求体使用 contents[].parts[]，文字和图片是相邻的 part。

curl https://api.muxllm.com/v1beta/models/MODEL_NAME:generateContent \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "描述图片中的布局；不清楚的文字标记为无法辨认。"
          },
          {
            "inline_data": {
              "mime_type": "image/jpeg",
              "data": "BASE64_IMAGE_DATA"
            }
          }
        ]
      }
    ]
  }'

部分 Gemini SDK 可能把 REST 字段映射为不同语言风格的属性名。使用 SDK 时以该 SDK 当前类型定义为准；直接发送 JSON 时保持网关接受的 REST 字段结构。

Multiple Images

多图顺序就是语义的一部分

若具体模型和协议支持多图片，可以在同一消息中依次加入多个图片块，并在文字中使用“第一张”“第二张”等明确指代。

Privacy & Security

上传前先完成数据分级

1. 01最小化内容

   裁剪到完成任务需要的区域，遮盖身份证、联系方式、付款码和其他无关信息。

2. 02移除元数据

   清理 EXIF 和定位信息，并确认文件扩展名与真实 MIME 一致。

3. 03控制 URL

   远程资源使用短期、最小权限链接；避免把签名 URL 写入聊天、工单或公开日志。

4. 04限制日志

   只记录哈希、字节数、MIME、状态码和脱敏请求 ID，不记录 Base64 正文。

5. 05隔离不可信文本

   图片中的指令、二维码和网页截图均视为不可信输入，不得据此泄露密钥或执行高风险操作。

Troubleshooting

从协议、能力和载荷三层定位

Official Sources

三种协议的图片内容块必须分开核对

Controlled Acceptance

一次最小视觉请求的验收顺序

1. 01选择明确模型

   从模型广场复制 MODEL_NAME，另行确认该模型具备视觉能力及目标协议。

2. 02准备无隐私测试图

   使用单张低分辨率图片，记录 MIME、字节数和预期可观察内容。

3. 03限制费用和次数

   使用专用低额度 YOUR_API_KEY，先批准一次调用和明确停止条件。

4. 04执行最小请求

   只保留模型、单条用户消息、单个图片块和一个可客观判断的问题。

5. 05保存脱敏证据

   记录状态码、响应字段、耗时和结果是否符合图片事实；不保存 Key 或图片正文。