DeepSeek 多模态 API 接入踩坑实录：vision 请求与文本请求的差异及 Cursor / Cline 配置全流程

ofoxcoding

51人浏览 · 2026-06-19 15:21:46

ofoxcoding · 2026-06-19 15:21:46 发布

最近我在改项目里的图片理解模块，尝试接入 DeepSeek 的多模态识图功能。结果发现直接把旧的文本 API 代码拿来改一改根本跑不通——vision 请求的 image_url 传参格式、content 字段结构，这些地方和纯文本 API 存在差异。这篇把我踩过的坑记下来，供参考。

注意：本文基于个人实测经验整理，部分细节（如具体限制数值、定价）请以 DeepSeek 官方文档为准，官方文档更新可能比本文更及时。

这篇适合谁

已经在用 DeepSeek 文本 API（deepseek-chat / deepseek-reasoner），想接入多模态识图的开发者
用 Cursor / Cline / Claude Code 这类工具，想接入 DeepSeek 多模态能力的
被 image_url is not supported by this model 这个报错卡住的人

整体流程

确认你的 API Key 有多模态权限（建议登录平台后台核查，不同 Key 的权限范围可能不同）
使用正确的 endpoint 路径和模型标识符
构造多模态请求体——content 字段从字符串变数组
处理 image_url 传参格式（base64 和 URL 两种写法）
根据官方文档设置 max_tokens

graph TD
    A[获取 API Key] --> B{Key 是否有多模态权限?}
    B -->|是| C[使用多模态 endpoint]
    B -->|否/不确定| D[登录平台后台确认或开通]
    D --> C
    C --> E[构造 image_url 请求体]
    E --> F{图片来源?}
    F -->|网络图片| G[直接传 URL]
    F -->|本地图片| H[base64 编码后传入]
    G --> I[按官方文档设置 max_tokens]
    H --> I
    I --> J[发送请求 & 解析响应]

先说结论

差异点	纯文本 API	多模态 Vision API
model 标识符	`deepseek-chat`	请查阅官方文档获取当前正确的多模态模型 ID
content 字段类型	字符串	数组（混合 text + image_url）
max_tokens	参考官方文档默认值	参考官方文档，建议显式设置
图片格式	不支持	base64 / URL 均可，大小限制请查阅官方文档

关于模型 ID：DeepSeek 官方文档会列出当前可用的多模态模型标识符，接入前请先在 platform.deepseek.com/docs 确认正确的 model ID，避免因模型名称变更导致 404 错误。

第一步：确认 Key 权限 & 使用正确 endpoint

如果你用文本 API 的 endpoint 发图片请求，会收到类似这样的报错：

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

这个报错信息有一定误导性——它说 "this model" 不支持，但实际上可能是 endpoint 或 model ID 不对。换成官方文档指定的多模态 endpoint 和模型标识符后，问题通常会消失。

endpoint 配置示例（具体路径请以官方文档为准）：

from openai import OpenAI

# 请将 base_url 和 model 替换为官方文档中当前有效的值
client = OpenAI(
    api_key="your-key",
    base_url="https://api.deepseek.com/v1"  # 请核实官方文档中的正确路径
)

第二步：构造多模态请求体

纯文本 API 的 content 是个字符串，多模态要改成数组：

messages = [{"role": "user", "content": [
    {"type": "text", "text": "描述这张图片"},
    {"type": "image_url", "image_url": {"url": img}}
]}]

这里 img 有两种写法。

方式一：网络图片直接传 URL

img = "https://example.com/photo.jpg"

方式二：本地图片转 base64

import base64
with open("local.png", "rb") as f:
    img = f"data:image/png;base64,{base64.b64encode(f.read()).decode()}"

注意 base64 前缀必须带 MIME type（data:image/png;base64,），不带的话不会报错，但模型可能无法正确识别图片内容。这个细节排查起来比较费时间。

第三步：设置 max_tokens

建议在多模态请求中显式设置 max_tokens，而不是依赖默认值。原因是：如果实际上限低于你的预期值，输出可能在没有错误提示的情况下被截断，表现为回复突然断在半句话中间。

resp = client.chat.completions.create(
    model="<官方文档中的多模态模型 ID>",
    messages=messages,
    max_tokens=4096  # 建议显式声明，具体上限请查阅官方文档
)

关于多模态请求的具体 max_tokens 上限，请以 DeepSeek 官方文档为准。本文此前提到的"4096 隐性上限"为个人实测观察，官方未公开明确说明，仅供参考。

完整调用示例

from openai import OpenAI

# 请将 base_url 和 model ID 替换为官方文档中当前有效的值
client = OpenAI(
    api_key="your-key",
    base_url="https://api.deepseek.com/v1"  # 请核实
)

messages = [{"role": "user", "content": [
    {"type": "text", "text": "这张截图里的报错是什么意思？"},
    {"type": "image_url", "image_url": {"url": "https://i.imgur.com/xxx.png"}}
]}]

resp = client.chat.completions.create(
    model="<官方文档中的多模态模型 ID>",  # 请核实
    messages=messages,
    max_tokens=4096
)
print(resp.choices[0].message.content)

通过聚合网关调用

如果你同时在用多个厂商的模型，每个厂商维护一套 Key 比较繁琐。聚合 API 网关（如 OpenRouter 等）可以统一管理，改一个 base_url 就能切换模型。

注意：选择聚合网关时，建议提前确认该服务是否稳定可用、是否支持你需要的模型，以及实际的手续费比例（各平台收费方式不同，请以各平台官网公示为准）。本文不对具体第三方服务的可用性和定价作背书。

# 以 OpenRouter 为例（请自行核实当前可用性和模型 ID）
client = OpenAI(
    api_key="your-openrouter-key",
    base_url="https://openrouter.ai/api/v1"
)

好处是一个 Key 能调多家模型，不用每个平台单独充值，团队使用时也便于统一审计消耗。

不同场景怎么选

场景	推荐方案	理由
个人项目、偶尔看图	直连 DeepSeek 官方 API	简单直接，价格参考官方定价页
团队项目、多人共用 Key	聚合网关（统一计费审计）	能看到每个人的消耗明细
需要对比多个模型识图效果	聚合网关切模型	改一个参数就能 A/B 测试
Cursor / Cline 里用	改 base_url 和 model 字段	注意 model 字段要手动填写正确的多模态模型 ID
图片量大、需要批处理	本地部署 DeepSeek-VL2	官方开源（可在 HuggingFace 获取），无 API 调用费