DeepSeek-v4-flash-vision-exp 体验版

# 视觉能力 | DeepSeek API 文档 来源：https://api-docs.deepseek.com/guides/vision/ `deepseek-v4-flash-vision-exp` 模型接受图像与文本一同输入，因此您可以请求模型描述图像、读取截图中的文字、分析图表等。 **支持的图像格式：JPEG、PNG、GIF 和 WebP**。格式由实际文件内容检测，而非文件名或声明的 MIME 类型。 --- ## 发送图像（https://api-docs.deepseek.com/guides/vision/#sending-images） 您有三种方式向模型提供图像。所有方式均使用标准的 OpenAI 兼容聊天补全格式，其中 `content` 是一个块数组而非纯字符串。 这三种方法同样可用于 Responses API（https://api-docs.deepseek.com/guides/responses_api#image-input），图像通过 `input_image` 内容块传输。 以下示例的 `base_url` 为 `https://api.deepseek.com`。 ### 1. Base64 编码的图像（内联）（https://api-docs.deepseek.com/guides/vision/#1-base64-encoded-image-inline） 对图像进行编码并作为 `data:` URL 直接嵌入请求中。这是处理本地文件最简单的选项。 编码后的数据计入 **48 MiB** 的请求体限制（参见 [限制](https://api-docs.deepseek.com/guides/vision/#limits)）。 ```python 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-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) ``` ```bash 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（https://api-docs.deepseek.com/guides/vision/#2-external-image-url） 传递一个公开可访问的 `http(s)` 链接，模型将为您下载图像。 URL 长度不得超过 **8192 字符**，图像文件大小不得超过 **32 MiB**，且下载必须在 **60 秒**内完成。如果您的链接更长，请使用 base64 数据 URL 或 Files API。 ```python 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 上传的文件（https://api-docs.deepseek.com/guides/vision/#3-reference-a-file-uploaded-via-the-files-api） 先通过 [Files API](https://api-docs.deepseek.com/guides/files_api) 上传一张图像，然后在请求中引用其 `file_id`。 当您需要在多个请求中重复使用同一张图像，或者图像大小超过 48 MiB 内联限制时，这是最佳选项。 与内联图像不同，通过 Files API `file_id` 引用的图像大小上限为 64 MiB，且不受单张图像 32 MiB 检查的限制。 使用带有返回的 `file_id`（格式为 `file-api-...`）的 `file` 内容块： ```python 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` 块可以通过 `file_data` 而非 `file_id` 以 base64 格式内联携带图像（两者互斥）： ```json { "type": "file", "file_data": "data:image/jpeg;base64,...", "filename": "image.jpg" } ``` --- ## 详细级别（https://api-docs.deepseek.com/guides/vision/#detail-level） 对于 `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（https://api-docs.deepseek.com/guides/vision/#when-to-use-the-files-api） 内联图像（base64 或 `file_data`）计入 **48 MiB** 的请求体大小限制。 请考虑使用 [Files API](https://api-docs.deepseek.com/guides/files_api)，当： - 单个请求会超过请求体大小限制时。 - 图像大于 32 MiB，这仅可通过 Files API 实现。 - 您需要在多个请求中引用同一张图像，并希望避免每次重新上传时。 --- ## 令牌使用（https://api-docs.deepseek.com/guides/vision/#token-usage） 图像根据其尺寸转换为令牌，这些令牌与文本令牌一起计费。在推理之前，每张图像都会自动调整大小： - 总像素数低于约 384×384 的图像会被放大，同时保持宽高比。 - 较大的图像会被缩小，同时保持宽高比，使调整后的总像素数大致相当于一张 **800×800** 图像的像素数。 因此，每张图像的令牌数存在 **384** 个令牌的上限：例如，一张 2000×2000 的图像和一张 5000×5000 的图像在调整大小后消耗相同数量的令牌。 当请求包含多张图像时，每张图像根据相同规则独立计数——多图像请求没有单独的计算方式。 要估算特定尺寸图像的令牌成本，请使用 [令牌与令牌使用](https://api-docs.deepseek.com/quick_start/token_usage) 页面上的图像令牌计算器。 --- ## 限制（https://api-docs.deepseek.com/guides/vision/#limits） | 限制 | 值 | | :--- | :--- | | 支持的格式 | 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: 限制](https://api-docs.deepseek.com/guides/files_api#limits)。 --- ## 限制（https://api-docs.deepseek.com/guides/vision/#restrictions） - 图像仅在 `user` 消息中受支持：在 `system` 或 `assistant` 消息中的图像会返回 `400` 错误。 - 仅视觉模型（`deepseek-v4-flash-vision-exp`）接受图像；其他模型返回 `400` 错误（“This model does not support image”）。 - 包含保留图像占位符令牌的用户文本将被拒绝，并返回 `400` 错误。 --- ## 在 Anthropic API 中使用图像（https://api-docs.deepseek.com/guides/vision/#using-images-with-the-anthropic-api） 除了上述 OpenAI 兼容端点外，您还可以通过 Anthropic 兼容的 `/messages` 端点（`base_url`=`https://api.deepseek.com/anthropic`）发送图像。 有关一般设置，请参阅 [Anthropic API](https://api-docs.deepseek.com/guides/anthropic_api)。 区别在于图像内容块的结构。Anthropic 使用带有 `source` 对象的 `image` 块，其 `type` 是 `base64`、`url` 或 `file` 之一，而非 `image_url`。 ```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 方法： | `source.type` | 等效的 OpenAI 方法 | 备注 | | :--- | :--- | :--- | | `base64` | Base64 编码图像 | 需要 `media_type` 字段（`image/jpeg`、`image/png`、`image/gif` 或 `image/webp`）。 | | `url` | 外部图像 URL | 最大 8192 字符。 | | `file` | Files API `file_id` | 需要头部 `anthropic-beta: files-api-2025-04-14`。 | --- ## 在 Responses API 中使用图像（https://api-docs.deepseek.com/guides/vision/#responses-api） `deepseek-v4-flash-vision-exp` 模型也通过 OpenAI 兼容的 [Responses API](https://api-docs.deepseek.com/guides/responses_api#image-input) 接受图像。 相同的三种输入方法（base64 数据 URL、外部 `http(s)` URL、Files API `file_id`）和相同的[限制](https://api-docs.deepseek.com/guides/vision/#limits)适用；只有内容块结构不同——图像通过 `user`/`developer` 消息或 `function_call_output`/`custom_tool_call_output` 项的输出中的 `input_image` 部分传输。 ```python response = client.responses.create( model="deepseek-v4-flash-vision-exp", 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 指南](https://api-docs.deepseek.com/guides/responses_api#image-input)。