通过 OpenAI 兼容 /chat/completions 发送图片与多段消息

多段消息是什么

在 OpenAI 兼容的 /chat/completions 接口中，messages 里每条消息的 content 字段除了可以是字符串，还可以是一个数组。数组中的每个元素称为一个“内容块”（content part），可以包含文本、图片等不同类型的媒体。这种结构让模型能同时处理文字和视觉信息。

例如，一条用户消息可以包含：

• 一段文字描述
• 一张或多张图片

模型会将这些内容块按顺序理解并生成回复。

构造 content 数组的基本格式

以下是一个典型的多段消息结构（以 JSON 表示）：

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请描述这张图片" },
        { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } }
      ]
    }
  ]
}

要点：

• content 是数组，不是字符串。
• 每个元素必须有 type 字段，常见值有 text、image_url。
• 文本块使用 text 字段存放具体文字。
• 图片块使用 image_url 对象，其中 url 字段可以是网络地址或 Base64 数据 URI。

传递图片的两种方式

1. 通过 URL 传递

如果图片已经托管在公网可访问的地址，可以直接把 URL 放进 image_url.url。

{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/photo.png"
  }
}

注意：部分模型要求 URL 必须能直接访问，不能有鉴权或重定向。

2. 通过 Base64 传递

如果图片在本地或需要内联传输，可以编码为 Base64 并拼成 Data URI。

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

Data URI 的格式为：data:<MIME类型>;base64,<编码数据>。

Base64 会让请求体积增大，适合小图或对隐私要求较高的场景。

不同模型的字段差异

聚合站通过统一的 OpenAI 兼容接口转发请求，但底层模型对多段消息的支持细节可能不同。以下是常见差异：

Claude 系列

• 支持 image_url 类型，但通常要求 url 字段为 Base64 Data URI，不直接支持公网 URL（取决于具体接入方式）。
• 图片格式支持 JPEG、PNG、GIF、WebP。
• 内容块顺序会影响理解，建议先放文字再放图片或按逻辑排列。

GPT 系列

• 原生支持 image_url 和 Base64 Data URI。
• 可选 detail 字段（如 "detail": "high"）控制图片解析精度，但并非所有版本都支持。
• 对图片尺寸和格式有默认限制，通常支持 JPEG、PNG、GIF、WebP。

Qwen 系列

• 支持 image_url 结构，但部分版本可能仅接受 Base64 或特定 URL 格式。
• 支持的图片格式以官方文档为准，常见为 JPEG、PNG。
• 多图消息中，图片数量可能有限制。

其他模型

DeepSeek、GLM、Kimi 等模型的多模态能力正在演进，部分版本可能只支持纯文本。发送图片前最好确认目标模型是否具备视觉理解能力。

跨模型兼容的实践建议

1. 优先使用 Base64 Data URI：兼容性最好，多数模型都接受。
2. 控制图片大小：过大的 Base64 会导致请求超时或超出 token 限制。
3. 格式选择 JPEG 或 PNG：这两种格式被广泛支持。
4. 检查模型能力：不是所有模型都能处理图片，纯文本模型收到图片块可能报错或忽略。
5. 测试单图再试多图：逐步增加复杂度，便于定位问题。

常见错误与排查

• 请求报 400：检查 content 是否为数组，每个元素是否有 type，图片块是否包含 image_url.url。
• 模型忽略图片：确认模型支持视觉输入，且图片编码正确。
• 响应超时：图片太大或网络 URL 不可达，尝试换 Base64 并压缩图片。
• Base64 格式错误：确保前缀 data:image/jpeg;base64, 完整，且编码数据无换行。

小结

通过构造 content 数组，你可以在一次请求中发送文字和图片。虽然聚合站提供统一的 OpenAI 兼容接口，但不同模型对字段和媒体类型的支持存在差异。使用 Base64 Data URI、控制图片体积、并提前确认模型能力，能显著提高多段消息的成功率。