进阶 api-docs.deepseek.com 2026-10-13 22:45:35 · 23 阅读
第19章 Vision 视觉能力
Vision
deepseek-flash 模型支持同时接收图像和文本，你可以让模型描述图片、识别截图中的文字、分析图表等。旧模型名 deepseek-v4-flash-vision-exp 仍然可用，但该模型已退役，相关请求同样由最新的 Flash 模型处理。
支持的图像格式：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 base64
from openai import OpenAI
client = 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-flash",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "这张图片里有什么？"},
{
"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-flash",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "这张图片里有什么？"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,"}}
]
}
]
}'
2. 外部图片 URL 传入一个公开可访问的 http(s) 链接，模型会自动为你下载该图片。URL 长度不得超过 8192 个字符，图片文件大小不得超过 32 MiB，且下载必须在 60 秒内完成。如果链接过长，请改用 base64 data URL 或 Files API。 ```python response = client.chat.completions.create(
model="deepseek-flash",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "描述这张图片。"},
{
"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-...）配合 file content block： ```python response = client.chat.completions.create(
model="deepseek-flash",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "这张图片里有什么？"},
{"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"},
],
}
],
)
print(response.choices[0].message.content)
``` 或者，也可以使用 file block 通过 file_data 以内联 base64 的形式携带图片，代替 file_id（二者互斥）： ```json {
"type": "file",
"file_data": "data:image/jpeg;base64,",
"filename": "image.jpg"
}
``` 细节级别 对于 image_url 输入，你可以可选地设置 detail 字段以控制图片处理方式： 值 行为 low 图片在下推前会被缩小到 512×512。当精细视觉细节不重要时，速度更快、成本更低。 high 保留原图。（为兼容性提供；等效于 original。） original 保留原图。 auto 自动选择。目前等效于 original。 ```json {
"type": "image_url",
"image_url": {"url": "https://example.com/image.jpg", "detail": "low"}
}
```
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 的三种方法： source.type等价的 OpenAI 方法说明base64Base64 编码的图片需要指定 media_type 字段（image/jpeg、image/png、image/gif 或 image/webp）。url外部图片 URL最长 8192 个字符。fileFiles API 的 file_id需要请求头 anthropic-beta: files-api-2025-04-14。 在 Responses API 中使用图片 deepseek-flash 模型也支持通过 OpenAI 兼容的 Responses API 传入图片。三种输入方式（base64 data URL、外部 http(s) URL、Files API 的 file_id）以及相关限制完全相同，只是 content 部分的结构不同——图片放在 input_image 部分中，可以出现在 user / developer 消息里，也可以出现在 function_call_output / custom_tool_call_output 项的输出中： response = client.responses.create(
model="deepseek-flash",
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": "What is in this image?"},
{"type": "input_image", "image_url": "https://example.com/image.jpg", "detail": "low"},
],
}
],
)
print(response.output_text)
input_image 部分支持 detail 字段，含义与上文相同（low / high / original / auto）。通过 file_id 提供图片时 detail 会被忽略，且 image_url 和 file_id 不能同时使用。 关于字段语义、限制（system / assistant 消息中的图片会返回 400 错误）以及工具输出中的图片，请参阅 Responses API 指南。
from openai import OpenAI
client = OpenAI(api_key="
with open("image.jpg", "rb") as f:
b64 = base64.b64encode(f.read()).decode("utf-8")
response = client.chat.completions.create(
model="deepseek-flash",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "这张图片里有什么？"},
{
"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-flash",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "这张图片里有什么？"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,
]
}
]
}'
2. 外部图片 URL 传入一个公开可访问的 http(s) 链接，模型会自动为你下载该图片。URL 长度不得超过 8192 个字符，图片文件大小不得超过 32 MiB，且下载必须在 60 秒内完成。如果链接过长，请改用 base64 data URL 或 Files API。 ```python response = client.chat.completions.create(
model="deepseek-flash",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "描述这张图片。"},
{
"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-...）配合 file content block： ```python response = client.chat.completions.create(
model="deepseek-flash",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "这张图片里有什么？"},
{"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"},
],
}
],
)
print(response.choices[0].message.content)
``` 或者，也可以使用 file block 通过 file_data 以内联 base64 的形式携带图片，代替 file_id（二者互斥）： ```json {
"type": "file",
"file_data": "data:image/jpeg;base64,
"filename": "image.jpg"
}
``` 细节级别 对于 image_url 输入，你可以可选地设置 detail 字段以控制图片处理方式： 值 行为 low 图片在下推前会被缩小到 512×512。当精细视觉细节不重要时，速度更快、成本更低。 high 保留原图。（为兼容性提供；等效于 original。） original 保留原图。 auto 自动选择。目前等效于 original。 ```json {
"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 一起计费。
在推理前，每张图片都会自动缩放：
- 总像素低于约 544×544 的图片，会在保持宽高比的前提下放大。
- 更大的图片会在保持宽高比的前提下缩小，使缩放后的总像素数接近 1300×1300 的图片。
因此，单张图片的 token 上限为 1024：例如，一张 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。
限制条件
- 仅支持在 user message 中使用图片。在 system 或 assistant message 中包含图片将返回 400 错误。
在 Anthropic API 中使用图片
除上述 OpenAI 兼容端点外，你还可以通过 Anthropic 兼容的 /messages 端点（base_url = https://api.deepseek.com/anthropic）发送图片。通用配置请参阅 Anthropic API。
差异在于图片内容块的结构。Anthropic 不使用 image_url，而是使用包含 source 对象的 image 块，其 type 为 base64、url 或 file 之一：
import anthropic
client = anthropic.Anthropic() # ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
message = client.messages.create(
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 的三种方法： source.type等价的 OpenAI 方法说明base64Base64 编码的图片需要指定 media_type 字段（image/jpeg、image/png、image/gif 或 image/webp）。url外部图片 URL最长 8192 个字符。fileFiles API 的 file_id需要请求头 anthropic-beta: files-api-2025-04-14。 在 Responses API 中使用图片 deepseek-flash 模型也支持通过 OpenAI 兼容的 Responses API 传入图片。三种输入方式（base64 data URL、外部 http(s) URL、Files API 的 file_id）以及相关限制完全相同，只是 content 部分的结构不同——图片放在 input_image 部分中，可以出现在 user / developer 消息里，也可以出现在 function_call_output / custom_tool_call_output 项的输出中： response = client.responses.create(
model="deepseek-flash",
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": "What is in this image?"},
{"type": "input_image", "image_url": "https://example.com/image.jpg", "detail": "low"},
],
}
],
)
print(response.output_text)
input_image 部分支持 detail 字段，含义与上文相同（low / high / original / auto）。通过 file_id 提供图片时 detail 会被忽略，且 image_url 和 file_id 不能同时使用。 关于字段语义、限制（system / assistant 消息中的图片会返回 400 错误）以及工具输出中的图片，请参阅 Responses API 指南。
