DeepSeek发布v4-flash-vision-exp视觉模型接入指南

在此页面 ## 视觉能力 deepseek-v4-flash-vision-exp 模型接受图像与文本，因此你可以要求模型描述图片、从截图中读取文字、分析图表等。支持的图像格式：JPEG、PNG、GIF 和 WebP。格式是从实际文件内容中检测的，而非文件名或声明的 MIME 类型。 ## 发送图像​ 有三种方式为模型提供图像。它们均使用标准的 OpenAI 兼容 Chat Completions 格式，其中 content 是块数组而非纯字符串。Responses API 中也提供相同的三种方法，图像通过 input_image 内容部分传递。以下示例的 base_url 为 https://api.deepseek.com。 ## 1. Base64 编码图像（内联）​ 对图像进行编码并将其作为 data: URL 直接嵌入请求中。这是处理本地文件的最简单选项。编码后的数据计入 48 MiB 的请求体限制（参见 Limits）。 ``` import base64from openai import OpenAIclient = OpenAI(api_key="", base_url="https://api.deepseek.com")with open("image.jpg", "rb") as f: b64 = base64.b64encode(f.read()).decode("utf-8")response = client.chat.completions.create( model="deepseek-v4-flash-vision-exp", messages=[ { "role": "user", "content": [ {"type": "text", "text": "What is in this image?"}, { "type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{b64}"}, }, ], } ],)print(response.choices[0].message.content) ``` ``` curl https://api.deepseek.com/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "model": "deepseek-v4-flash-vision-exp", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "What is in this image?"}, {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,"}} ] } ] }' ``` ## 2.外部图像 URL​ 传递一个公开可访问的 http(s) 链接，模型会为你下载图像。URL 长度不得超过 8192 个字符，图像文件大小不得超过 32 MiB，且下载必须在 60 秒内完成。如果你的链接更长，请改用 base64 data URL 或 Files API。 ``` response = client.chat.completions.create( model="deepseek-v4-flash-vision-exp", messages=[ { "role": "user", "content": [ {"type": "text", "text": "Describe this image."}, { "type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}, }, ], } ],)print(response.choices[0].message.content) ``` ## 3.引用通过 Files API 上传的文件 使用 Files API 上传一次图像，然后在请求中引用其 file_id。当您在多个请求中重复使用同一张图像，或者图像导致请求体超过 48 MiB 的内联限制时，这是最佳选择。与内联图像不同，通过 Files API file_id 引用的图像最大可达 64 MiB，且不受每张图像 32 MiB 的检查限制。使用包含返回的 file_id（格式为 file-api-...）的文件内容块：``` response = client.chat.completions.create( model="deepseek-v4-flash-vision-exp", messages=[ { "role": "user", "content": [ {"type": "text", "text": "What is in this image?"}, {"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"}, ], } ],)print(response.choices[0].message.content) ``` 或者，文件块可以通过 file_data 而非 file_id 以 base64 形式携带内联图像（两者互斥）：``` { "type": "file", "file_data": "data:image/jpeg;base64,", "filename": "image.jpg"} ``` ## 详细程度 对于 image_url 输入，您可以选择设置 detail 字段来控制图像的处理方式：值 | 行为 low | 在推理前将图像下采样至 512×512。当精细视觉细节不重要时，此方式更快且更便宜。high | 保留原始图像。（出于兼容性提供；等同于 original。）original | 保留原始图像。auto | 自动选择。目前等同于 original。``` { "type": "image_url", "image_url": {"url": "https://example.com/image.jpg", "detail": "low"}} ``` ## 何时使用 Files API 内联图像（base64 或 file_data）计入 48 MiB 的请求体大小限制。在以下情况下考虑使用 Files API： - 单个请求会超出请求体大小限制。 - 图像大于 32 MiB，这只能通过 Files API 实现。 - 您在多个请求中引用同一张图像，并希望避免每次重新上传。 ## Token 使用情况 图像根据其尺寸转换为 token，这些 token 将与您的文本 token 一起计费。在推理之前，每张图片都会自动调整大小： - 总像素数低于约 384×384 的图像会在保持纵横比的同时放大。 - 较大的图像会在保持纵横比的同时缩小，以便调整大小后的总像素数大致相当于 800×800 图像的像素数。因此，每张图像的上限为 384 个 token：例如，2000×2000 的图像和 5000×5000 的图像在调整大小后消耗的 token 数量相同。当请求包含多张图像时，每张图像均按同一规则独立计数——针对多图像请求没有单独的计费方式。要估算特定尺寸图像的 token 成本，请使用 Token & Token Usage 页面上的图像 token 计算器。 ## 限制 | 限制项 | 值 | | --- | --- | | 支持的格式 | JPEG、PNG、GIF、WebP | | 外部 URL 长度 | 8192 个字符 | | 请求体大小 | 48 MiB | | 单张图像最大尺寸（base64 / 外部 URL） | 32 MiB | | 单张图像最大尺寸（Files API file_id） | 64 MiB | | 每次请求的最大图像数量 | 600 | | 每次请求的总图像大小上限 | 不含 file_id 图像的请求为 64 MiB；含 file_id 图像的请求最高可达 200 MiB | | 图像最大维度 | 每侧 8192 px；当请求包含 15 张或更多图像时，降至每侧 4096 px | 有关通过 Files API 上传文件的存储和上传配额，请参阅 Files API: Limits。 ## 限制说明 - 仅支持在用户消息中使用图像：系统消息或助手消息中的图像会返回 400 错误。 - 仅视觉模型（deepseek-v4-flash-vision-exp）接受图像；其他模型会返回 400 错误（"This model does not support image"）。 - 包含保留图像占位符 token 的用户文本将被拒绝，并返回 400 错误。 ## 在 Anthropic API 中使用图像 除了上述兼容 OpenAI 的端点外，你还可以通过兼容 Anthropic 的 /messages 端点发送图像（base_url = https://api.deepseek.com/anthropic）。常规设置请参考 Anthropic API。区别在于图像内容块的形状。Anthropic 不使用 image_url，而是使用一个 source 对象类型为 base64、url 或 file 的 image 块： ```python import anthropic client = anthropic.Anthropic() # ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic message = client.messages.create( model="deepseek-v4-flash-vision-exp", max_tokens=1024, messages=[ { "role": "user", "content": [ {"type": "text", "text": "What is in this image?"}, { "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "", }, }, ], } ], ) print(message.content) ``` 这三种 source 变体对应于上述 OpenAI 的方法：