聚合大模型 API 多模态调用排障指南

前言

有开发者在使用聚合 API 调用 Kimi、Qwen 多模态模型识别图片或 PDF 文档时，会遇到固定提示：没有检测到图片。请提供需要识别的图片。同一个图片、相同提示词，直接调用模型厂商官方 API 可正常识别，但平台其他开发者未复现同类故障。从检查使用推断：该问题一般是请求体构造错误，或是跨厂商中转链路中图片 / 文件被静默丢弃。不属于平台全局转发故障，

报错本质

模型成功解析了对话消息messages，但在消息体内未识别到合法图片资源对象。该报错不代表图片本身损坏或 Base64 编码失效，常见两种根因：消息结构不符合协议规范；或者图片数据在到达上游模型前，在链路中丢失。

一、客户端请求构造五大常见问题

1. content 数组被二次序列化为字符串（最高发问题）

OpenAI 兼容多模态协议要求，message.content必须是数组对象，数组内包含text文本块与image_url图片块。Kimi 官方文档明确提示：禁止将 JSON 数组序列化后以字符串形式写入 content，该格式属于非标准写法，上游模型不会解析其中的图片对象。

✅ 正确：content 直接为数组 ❌ 错误：手动执行JSON.stringify，将数组包装成字符串

现象：上游模型只会把 content 整体当作普通文本，忽略里面的 image_url 图片信息。说明：主流 SDK 会自动组装 JSON 结构，不会出现该问题；手写请求体、自行拼接 JSON 字符串时极易踩坑。

2. Base64 编码格式异常

图片 Base64 传参失败常见 3 种情况：

缺失 MIME 前缀：缺少data:image/jpeg;base64,标识；
二次 URL 编码：对 Base64 字符串额外执行 urlencode；
数据截断：大文件分片上传不完整，图片数据残缺。

快速验证方式：将当前 Base64 内容直接在厂商官方 API 测试。官方接口识别正常，则 Base64 本身无问题。

3. PDF 与图片接口逻辑不同（Kimi 重点说明）

图片、PDF 在 Kimi 接口是两套独立上传流程，不可复用同一套请求代码：

图片：直接使用image_url + Base64方式传入；
PDF：不可直接放入 image_url。需先调用文件上传接口/v1/files，设置purpose="file-extract"获取file_id，再在对话消息中引用该文件 ID。

Qwen 补充说明：绝大多数 Qwen-VL 版本原生不支持 PDF 解析，业务侧需要预先将 PDF 分页转图片再传入；仅 Qwen Omni 系列原生支持 PDF 文档。

4. 模型选择错误

调用多模态能力，必须选择视觉版本模型：

Kimi：kimi-k3 / kimi-k2.6
Qwen：qwen-vl-plus / qwen3-vl / Qwen Omni 系列

若传入纯文本模型，模型不会解析 image_url 字段，无法识别图片。

5. 请求头配置错误

请求头必须设置：Content-Type: application/json 使用application/x-www-form-urlencoded会造成嵌套 JSON 扁平化，破坏 content 数组结构。不要混用multipart/form-data和 JSON 请求体。

二、聚合 API 场景特有：中转链路静默丢图

上面是客户端侧问题。在聚合中转架构下，还会存在链路断层问题：请求不返回异常码，但图片在转发途中被静默丢弃。

断层 1：不同模型厂商多模态协议存在差异

各厂商图片传输规范并不完全对齐。例如 MiniMax 的/v1/chat/completions端点会直接忽略image_url结构，只能使用特定方式传递图片。聚合平台仅按 OpenAI 标准转发请求时，若上游厂商协议不兼容，不会返回报错，直接丢弃图片资源。

断层 2：模型能力元数据配置缺失

部分模型后端原生支持图片输入，但客户端 / 平台内部模型元数据表标记为纯文本模型。图片会在请求转发前直接拦截。典型现象：直接 curl 请求上游官方接口正常，经过聚合平台转发就失效。

断层 3：PDF 内部图片被解析器跳过

扫描版 PDF 存在特殊压缩编码（JBIG2Decode、CCITTFaxDecode）。如果 PDF 解析逻辑没有兼容这类编码，上传显示成功，但文档内图片不会被提取。若聚合平台内置 PDF 解析能力，该场景会出现图片静默丢失。

三、标准化排查清单

打印原始请求 JSON，检查messages[0].content类型：如果是字符串，代表多做了一层序列化。
对照测试：同一资源分别调用厂商官方 API 和聚合 API。
- 官方可正常识别：问题出在聚合中转链路；
- 官方同样报错：问题为客户端请求构造错误。
区分图片 / PDF：图片校验 Base64 前缀与编码；PDF 确认是否使用文件上传接口，或提前转图片。
校验模型标识，确认所选模型支持视觉能力。
确认聚合平台内该模型的能力元数据标记，确认平台已开启多模态支持。

最小可用调用示例（图片识别）

curl https://openstarry.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kimi-k3",
  "messages": [{
    "role": "user",
    "content": [
      {"type":"text","text":"提取图片中的全部文字"},
      {"type":"image_url","image_url":{"url":"data:image/jpeg;base64,此处替换你的base64"}}
    ]
  }]
}'

总结

聚合 API 对接多模态模型最隐蔽的难点就是静默丢图。普通参数错误会直接返回报错码；但图片丢失场景，模型只会提示未检测到图片，难以快速定位问题属于客户端还是中转层。

推荐优先使用「打印原始请求体 + 官方接口对照测试」这套排查方案，快速定位故障位置，减少联调耗时。

如在使用平台多模态接口过程中遇到其他问题，欢迎联系技术支持。

前言