deepseek-v4-pro 识图接口报 400 怎么办？两种 error message 不同但都是 400，排查方向完全不一样

deepseek-v4-pro 识图接口报 400 怎么办？两种 error message 不同但都是 400，排查方向完全不一样

上周三我在给一个电商客户做商品图自动标注的功能，用 deepseek-v4-pro 调多模态接口。纯文本聊天一切正常，Key 没问题，额度也够——但一传图片就 400。折腾了大半天才搞明白：同样是 HTTP 400，视觉模式有两处强制校验，error type 字段都是invalid_request_error，但 error message 文本不同，修法也完全不一样。一个是 base64 图片缺 data URI 前缀，另一个是 messages 数组里混了纯文本 role。

下面直接给排查路径，5 分钟能定位问题。

flowchart TD A[调用 deepseek-v4-pro 识图] --> B{返回 400?} B -->|是| C{看 error message} C -->|"image_url is not supported\n且模型名已确认正确"| D[检查 base64 前缀] C -->|"image_url is not supported\n且模型名有误或不支持视觉"| F[更换为支持视觉的模型] C -->|content must be a string| E[检查 messages 结构] B -->|否，返回 200| G[正常] D --> H[补上 data:image/jpeg;base64, 前缀] E --> I[system/assistant role 的 content 改回纯字符串]

为什么会出现这个问题

deepseek-v4-pro 的视觉模式对请求体的校验比纯文本接口严格很多。之前你 content 字段随便传个字符串就行，视觉模式要求 content 必须是数组格式，而且数组里每个元素的 type 和结构都有硬性约束。

关键点：纯文本调用同一个 Key 完全正常，不代表你的请求格式对多模态也合法。这俩是不同的校验逻辑。

报错场景一：base64 图片缺 data URI 前缀

这是我最先踩到的坑。完整报错长这样：

openai.BadRequestError: Error code: 400 - { 'error': {'message': 'Invalid content type. image_url is not supported for this model.', 'type': 'invalid_request_error'} }

注意：这个 message 有一定误导性——如果你模型名写的是 deepseek-v4-pro，问题大概率不是模型不支持视觉，而是 image_url 字段里的 url 值格式不对。我一开始是这么写的：

import base64 with open('product.jpg', 'rb') as f: b64 = base64.b64encode(f.read()).decode()

然后直接把b64塞进了 url 字段：

{"type": "image_url", "image_url": {"url": b64}}

这就炸了。DeepSeek 的视觉接口要求 base64 图片必须带完整的 data URI 前缀，格式是data:image/jpeg;base64,{实际base64内容}。你光传一串 base64 字符，服务端不知道这是什么格式，直接拒绝。

正确写法：

url_val = f"data:image/jpeg;base64,{b64}" {"type": "image_url", "image_url": {"url": url_val}}

注意 MIME type 要跟实际图片格式对应——PNG 就写image/png，WebP 就写image/webp。写错了也会 400。单张图片大小和格式限制请以官方文档为准。

报错场景二：messages 里混入纯文本 role 触发格式冲突

这个更隐蔽。修完 base64 前缀之后，还是 400，但 error message 变了：

openai.BadRequestError: Error code: 400 - { 'error': {'message': 'content must be a string when using this model.', 'type': 'invalid_request_error'} }

乍一看很困惑——明明用的是多模态模型，为什么要求 content 是 string？

查了半天发现问题在 messages 数组里。我的 system prompt 也用了数组格式的 content：

messages = [ {"role": "system", "content": [{"type": "text", "text": "你是图片分析助手"}]}, {"role": "user", "content": [...]}, ]

坑在这里：deepseek-v4-pro 的视觉模式下，system和assistant角色的 content 必须保持纯字符串，只有user角色的 content 才能是数组格式。你一旦给 system role 也传了数组，服务端就会报content must be a string——它校验的是非 user 角色的 content 类型。请注意这是 DeepSeek 接口的特有约束，与 OpenAI 原生 Vision API 的行为不同，建议以 DeepSeek 官方文档为准。

正确写法：

messages = [ {"role": "system", "content": "你是图片分析助手"}, {"role": "user", "content": [ {"type": "image_url", "image_url": {"url": url_val}}, {"type": "text", "text": "描述这张商品图"} ]}, ]

只有 user 的 content 用数组，其他 role 老老实实写字符串。

方案一：逐步排查法（推荐新手）

先跑通纯文本，确认基础链路没问题，再加图片测试。将以下代码合并为一个完整块直接运行：

from openai import OpenAI client = OpenAI(api_key="YOUR_KEY", base_url="https://api.deepseek.com") # 第一步：先跑纯文本 resp = client.chat.completions.create( model="deepseek-v4-pro", messages=[{"role": "user", "content": "你好"}] ) print(resp.choices[0].message.content)

纯文本通了，再加图片。图片先用公网 URL 测（排除 base64 编码问题），URL 通了再换 base64。

注：base_url此处使用https://api.deepseek.com，与 DeepSeek 官方文档一致；OpenAI SDK 会自动拼接路径，无需手动添加/v1。

方案二：写个校验函数提前拦截

每次构造 messages 前自动检查格式，本地就能拦住这两类错误，不用等服务端返回 400 再猜：

def validate_messages(messages): for msg in messages: if msg["role"] != "user" and not isinstance(msg["content"], str): raise ValueError(f"{msg['role']} content 必须是字符串") if msg["role"] == "user" and isinstance(msg["content"], list): for item in msg["content"]: if not isinstance(item, dict): raise TypeError(f"content 数组元素必须是 dict，实际是 {type(item)}") if "type" not in item: raise ValueError("content 数组元素缺少 'type' 字段") if item.get("type") == "image_url": url = item["image_url"]["url"] if not url.startswith(("http://", "https://", "data:")): raise ValueError("image_url 缺少合法前缀（http://、https:// 或 data:）")

在client.chat.completions.create之前调一下validate_messages(messages)即可。

方案三：用聚合 API 网关统一管理调用

如果你同时在用多个模型（比如 deepseek-v4-pro 做识图、claude-sonnet-5 做长文本），每家的格式要求都不一样，挺烦人的。可以把调用统一切到聚合网关，像 ofox.io、OpenRouter 这类第三方聚合服务商，网关层通常会在格式不合规时给出更明确的错误提示，方便定位问题。

以 ofox.io 为例，base_url替换后模型名填写方式与 OpenRouter（deepseek/deepseek-v4-pro）类似，其他代码结构不变：

client = OpenAI( api_key="your-gateway-key", base_url="https://openrouter.ai/api/v1" # 或替换为 ofox.io 对应端点 ) # 模型名示例（OpenRouter 格式）： model = "deepseek-v4-pro"

需要注意：网关能提供更清晰的错误提示，但 messages 结构里 system content 必须是字符串这个约束，还是得你自己在代码层面保证。网关不会帮你改 messages 结构。

两种 400 报错的快速对照表

常见问题 FAQ

Q: deepseek-v4-pro 纯文本正常但传图就 400，是不是 Key 权限不够？

不是 Key 的问题。同一个 Key 对文本和视觉接口都有效。400 说明请求到了服务端但格式校验没过，重点排查 content 数组结构和图片 URL 格式。

Q: base64 图片的 data URI 前缀写错了会怎样？

比如图片是 PNG 但你写了data:image/jpeg;base64,...，根据实测 DeepSeek 会尝试解码但可能返回识别结果异常或直接 400。建议用filetype或python-magic库先检测实际格式再拼前缀（imghdr模块自 Python 3.11 起标记为废弃，并于 Python 3.13 正式移除，不建议使用）。

Q: 多轮对话里 assistant 的回复要带图片怎么办？

根据实测，assistant role 的 content 只支持字符串。如果你需要在上下文里引用之前的图片分析结果，把结果文字放 assistant content 就行，不要把图片 URL 塞进去。

Q: 图片超过大小限制怎么处理？

压缩。用 Pillow 降分辨率或调 JPEG quality 到 85 基本都能大幅缩小体积。实测 1024×1024 的 JPEG 一般在 200KB-1MB。具体大小上限以官方文档为准。

Q: 能不能用聚合网关中转来辅助排查格式问题？

聚合网关（如 OpenRouter、ofox.io）能在格式出错时给出更明确的提示，方便排查。两者都兼容 OpenAI SDK 的调用方式，切换时只需替换base_url和对应的api_key，messages结构校验逻辑仍需在本地代码层面自行保证，网关不会帮你改 messages 结构。

最终方案

现在的做法是：本地加一个validate_messages函数做前置校验，线上通过聚合网关调用（方便切模型和看调用日志）。双重保障之后，这类 400 基本没再出现过。

如果你也遇到了类似的 400，先看 error message 里是image_url is not supported还是content must be a string——这俩修法完全不同，别搞混了。