图片理解接入指南：同时兼容 Chat API、Responses API、Claude API

如果你已经能用文字调用模型，那么把“图片理解”接进现有系统，真正要改的通常不是模型，而是请求体格式。OpenAI 官方文档里，Chat Completions 和 Responses 对图片输入的字段名不同；Anthropic 官方文档里，Claude Messages 又是另一套 content block 结构。好消息是，在 XAI Router 上，这三种请求形态都可以统一接到同一类支持视觉输入的模型，例如 gpt-5.4 或 gpt-5.4-mini。

本文只做一件事：把 OpenAI 和 Claude 官方示例里的图片输入写法，整理成可以直接发到 https://api.xairouter.com 的版本。为了方便统一说明，下面主示例默认使用 gpt-5.4；如果你更看重成本，也可以直接把 model 替换成 gpt-5.4-mini。

一句话结论

• 你已经在用 OpenAI 兼容聊天客户端：走 /v1/chat/completions
• 你想走 OpenAI 新接口或后续多模态工作流：走 /v1/responses
• 你现有系统是 Claude / Anthropic 兼容：走 /v1/messages
• 三种方式都可以把模型统一到支持图片输入的模型，比如 gpt-5.4 或 gpt-5.4-mini

三种接口的差别到底在哪？

注意：本文示例全部使用公网图片 URL。如果你后面要改成 Base64，也要继续遵循各自官方接口的字段结构，而不是直接把一个接口里的图片字段名照搬到另一个接口。

先准备一个环境变量

export XAI_API_KEY="sk-..."

把下面示例中的图片 URL 换成你自己的即可。为了方便对照，本文单图示例统一使用这张图片：

https://filelist.cn/disk/0/1.jpg

方案 A：Chat API

如果你现在手里已经有 OpenAI 兼容的聊天调用，这就是最小改动方案。你目前写的例子已经是正确方向了，只需要把 prompt 写得更明确一点，结果通常会更稳定。

curl https://api.xairouter.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "请解读这张图片，按 3 点输出：1. 主体；2. 关键细节；3. 可能场景。"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://filelist.cn/disk/0/1.jpg"
            }
          }
        ]
      }
    ],
    "max_tokens": 300
  }'

如果你只想保留你现在的写法，也完全可以，把上面的 "text" 改回 "解读一下" 就能继续用；如果你想换成更轻量的模型，把 model 改成 gpt-5.4-mini 即可。

方案 B：Responses API

如果你准备把图片、工具调用、后续工作流都统一到 OpenAI 新接口上，推荐直接走 /v1/responses。这里最大的区别只有两个：

1. messages 变成 input
2. 文本块和图片块分别写成 input_text、input_image

curl https://api.xairouter.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "请解读这张图片，按 3 点输出：1. 主体；2. 关键细节；3. 可能场景。"
          },
          {
            "type": "input_image",
            "image_url": "https://filelist.cn/disk/0/1.jpg"
          }
        ]
      }
    ],
    "max_output_tokens": 300
  }'

如果你的应用未来会接工具调用、结构化输出或更复杂的多模态链路，Responses 通常更值得作为主入口。想要更低成本时，同样可以把 model 改成 gpt-5.4-mini。

方案 C：Claude API

如果你现在用的是 Anthropic SDK、Claude Code 风格客户端，或者你接的是 Claude 兼容网关，那么图片块结构会再变一次。这里不是 image_url，而是 type: "image" 加上 source。

curl https://api.xairouter.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $XAI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "gpt-5.4",
    "max_tokens": 300,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://filelist.cn/disk/0/1.jpg"
            }
          },
          {
            "type": "text",
            "text": "请解读这张图片，按 3 点输出：1. 主体；2. 关键细节；3. 可能场景。"
          }
        ]
      }
    ]
  }'

如果你在用 Anthropic 官方 SDK，通常只需要把 baseURL 或 base_url 指到 https://api.xairouter.com，再把模型名改成你要用的目标模型，例如 gpt-5.4 或 gpt-5.4-mini。

支持多图输入吗？

支持。真正的区别不是“能不能传多张图”，而是每种接口往数组里追加图片块的写法不同：

• Chat API：继续在 content 里追加多个 image_url
• Responses API：继续在 content 里追加多个 input_image
• Claude API：继续在 content 里追加多个 image + source

多图最常见的用途不是“让模型看更多”，而是让它做更明确的事情，例如：

• 比较两张截图的差异
• 对多张商品图做一致性检查
• 汇总多页拍照内容
• 先逐张描述，再给综合判断

下面给三套最小可用示例。

多图示例 A：Chat API

curl https://api.xairouter.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "请分别描述这两张图片，并总结它们最明显的差异。"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://filelist.cn/disk/0/1.jpg"
            }
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://filelist.cn/disk/0/2.jpg"
            }
          }
        ]
      }
    ],
    "max_tokens": 400
  }'

多图示例 B：Responses API

curl https://api.xairouter.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "请分别描述这两张图片，并总结它们最明显的差异。"
          },
          {
            "type": "input_image",
            "image_url": "https://filelist.cn/disk/0/1.jpg"
          },
          {
            "type": "input_image",
            "image_url": "https://filelist.cn/disk/0/2.jpg"
          }
        ]
      }
    ],
    "max_output_tokens": 400
  }'

多图示例 C：Claude API

curl https://api.xairouter.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $XAI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "gpt-5.4",
    "max_tokens": 400,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://filelist.cn/disk/0/1.jpg"
            }
          },
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://filelist.cn/disk/0/2.jpg"
            }
          },
          {
            "type": "text",
            "text": "请分别描述这两张图片，并总结它们最明显的差异。"
          }
        ]
      }
    ]
  }'

多图时的三个建议

1. 不要只说“看看这几张图”，最好明确要求“先逐张描述，再给综合结论”。
2. 图片一多，输入 token、延迟和成本都会一起上升。
3. 如果你走 Claude 兼容请求，优先把图片块放前面，文本问题放后面。

什么时候选哪一个？

• 你要最小改动接入已有 OpenAI 客户端：选 Chat API
• 你准备长期做多模态、工具调用或新项目：选 Responses API
• 你已经有 Claude / Anthropic 兼容客户端或网关：选 Claude API

重点不是“哪一个更高级”，而是“你现在的客户端已经说哪种方言”。在 XAI Router 这一层，把方言翻译成本尽量留在网关，而不是逼业务侧重写。

常见坑

1）同样是传图片，字段名并不通用

• Chat API 不是 input_image
• Responses API 不是 image_url 对象
• Claude API 不是 image_url，而是 image + source

这也是很多“明明都是图片输入，为什么报参数错误”的根源。

2）优先用模型能直接访问的图片 URL

如果图片本来就放在对象存储、CDN 或公开地址，用 URL 最省事，也最接近官方示例。等你确认链路跑通，再考虑 Base64、本地上传、文件复用这些进阶形态。

3）Prompt 最好比“解读一下”更具体

图片理解时，模型会根据你的输出要求决定描述粒度。想要更稳定的结果，最好明确要求输出结构，比如“主体 / 细节 / 场景 / 风险 / OCR 文本”等。

你现在这段示例，其实已经能用

如果你当前已经有下面这段：

curl https://api.xairouter.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "解读一下"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://filelist.cn/disk/0/1.jpg"
            }
          }
        ]
      }
    ],
    "max_tokens": 300
  }'

那你其实已经跑在正确方向上了。这里继续用 gpt-5.4-mini 没问题；如果你想换成更强的模型，把 model 改成 gpt-5.4 也同样可以。接下来你要做的，不是绑定某一个模型名，而是根据你的客户端生态，决定是否继续保留 Chat API，还是统一切到 Responses API，或者给 Anthropic / Claude 客户端直接暴露 /v1/messages。

参考资料

• OpenAI 官方：Images and vision
• OpenAI 官方：Responses API
• OpenAI 官方：Chat Completions API
• Anthropic 官方：Vision
• Anthropic 官方：Messages examples