DeepSeek Vision API 完整教學：讓你的 Agent 看懂圖片
DeepSeek 官方 API 終於開放視覺（Vision）能力了！新的實驗模型 deepseek-v4-flash-vision-exp 可以同時接受圖片與文字，做到：
- 🖼️ 描述圖片內容
- 📄 讀取截圖中的文字（OCR）
- 📊 分析圖表與資料視覺化
支援 JPEG、PNG、GIF、WebP 四種格式——而且格式是從檔案實際內容偵測，不是看副檔名或 MIME 宣告。
📦 三種傳圖方式
DeepSeek Vision 使用標準的 OpenAI 相容格式，content 從純字串變成區塊陣列。共有三種方式，視你的使用情境選擇：
1️⃣ Base64 內嵌（最簡單，適合本地檔案）
把圖片編碼成 data: URL 直接放進請求。適用於本地檔案，但會佔用請求體上限（48 MiB）。
import base64
from openai import OpenAI
client = OpenAI(
api_key="<DeepSeek 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 版本：
curl https://api.deepseek.com/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <DeepSeek API Key>" \
-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,<BASE64_DATA>"}}
]
}
]
}'
2️⃣ 外部圖片 URL（適合公開圖片）
傳公開的 http(s) 連結，模型會自己下載。限制：URL 最多 8192 字元、圖片最多 32 MiB、下載必須在 60 秒內完成。URL 太長就改用 Base64 或 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 內嵌限制時的最佳選擇——file_id 圖片可達 64 MiB，且不受單圖 32 MiB 檢查限制。
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 欄位以 Base64 內嵌（與 file_id 互斥）：
{
"type": "file",
"file_data": "data:image/jpeg;base64,<BASE64_DATA>",
"filename": "image.jpg"
}
💰 Token 計費：每張圖最多 384 tokens
圖片會依尺寸轉換成 token，與文字 token 一起計費。推理前圖片會自動縮放：
- 總畫素低於約 384×384 → 等比放大
- 較大的圖片 → 等比縮小到約 800×800 的總畫素
因此每張圖有 384 tokens 的上限——例如 2000×2000 和 5000×5000 的圖片，縮放後消耗相同 token。多張圖各自獨立計算，沒有多圖優惠。
🔧 Detail 參數（控制品質與成本）
image_url 輸入可選 detail 欄位：
| 值 | 行為 | 適用 |
|---|---|---|
low | 縮小到 512×512 再推理 | 快速便宜、不需精細細節 |
high | 保留更多細節 | 需要精細辨識（小字/細節） |
🚫 官方限制表（必讀）
| 限制項目 | 數值 |
|---|---|
| 支援格式 | JPEG、PNG、GIF、WebP |
| 外部 URL 長度 | 8192 字元 |
| 請求體大小 | 48 MiB |
| 單圖上限（Base64/URL） | 32 MiB |
| 單圖上限（Files API） | 64 MiB |
| 每請求圖片數 | 600 張 |
| 每請求總圖大小 | 64 MiB（含 file_id 可到 200 MiB） |
| 圖片最大邊長 | 8192 px（≥15 張圖時降為 4096 px） |
注意事項：
- 圖片只在 user 訊息中支援——system/assistant 訊息放圖會回 400 錯誤
- 只有 vision 模型（
deepseek-v4-flash-vision-exp）接受圖片，其他模型回 400（“This model does not support image”） - 使用者文字含保留的圖片佔位 token 會被拒（400）
🔄 Anthropic 相容端點 + Responses API
除了 OpenAI 相容端點，還有兩種方式：
Anthropic 格式（base_url = https://api.deepseek.com/anthropic）
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": "<BASE64_DATA>",
},
},
],
}
],
)
print(message.content)
三種 source.type 對應：base64（需 media_type）、url（外部 URL）、file（Files API file_id，需 header anthropic-beta: files-api-2025-04-14）。
Responses API
同樣支援三種輸入方式，只是圖片改放在 input_image parts（user/developer 訊息或 function 輸出中）。
🎯 實戰建議
- 辨識截圖文字 → 用
detail: high提高 OCR 準確度 - 大量圖片處理 → 用 Files API 上傳一次重複參照，省流量又突破 32 MiB 限制
- 成本控制 → 不需要細節時用
detail: low（512×512），token 消耗更低 - 圖片很大 → 確認縮放規則（每圖最多 384 tokens），不用自己預先壓縮到 800×800
DeepSeek 的 Vision API 讓純文字模型終於長出「眼睛」——搭配 DeepSeek Harness 生態中的 ModLens 視覺插件，能讓你的 Agent 真正「看懂」世界。
來源：DeepSeek Vision API 官方文件｜官方數據截至 2026-08-19