Guide / DeepSeek Files API
DeepSeek Files API (2026): limiti, upload e file_id nella pratica
DeepSeek ha rilasciato senza clamore il suo primo endpoint per i file il 21 agosto 2026, insieme al modello vision — rendendo obsolete molte guide precedenti (diverse affermano ancora che l'API di DeepSeek "non ha una route per l'upload di file"). Questa guida include i limiti verificati, esempi di upload e riferimento in curl e Python, e quando usare i file al posto di base64.
La DeepSeek Files API carica un'immagine una sola volta e restituisce un file_id da referenziare in chat.
Effettua l'upload con purpose="user_data"; un file può arrivare fino a 64 MiB (finestra di upload di 10 minuti); lo spazio di archiviazione è di 25 GiB / 10.000 file per utente; periodo di conservazione da 1 ora a 30 giorni oppure permanente senza expires_after.
Fai riferimento ai file dalle chat di deepseek-v4-flash-vision-exp tramite un blocco {"type":"file","file_id":...} — le immagini con file_id possono raggiungere i 64 MiB per richiesta rispetto ai 32 MiB inline. Dall'endpoint compatibile con Anthropic, aggiungi l'header anthropic-beta: files-api-2025-04-14.
I limiti in sintesi
| Limite | Valore (documentazione ufficiale, 2026-08-21) |
|---|---|
| Formati | JPEG, PNG, GIF, WebP — rilevati dal contenuto del file, non dall'estensione |
| Per file | Max 64 MiB; l'upload deve completarsi entro 10 minuti |
| Per utente | 25 GiB di archiviazione; 10.000 file archiviati |
| Conservazione | Da 1 ora a 30 giorni, o permanente (omettendo expires_after) |
| Finalità | Deve essere user_data (unico scopo supportato, anche per il filtraggio della lista) |
| Dimensione nella richiesta | Immagini con file_id fino a 64 MiB per richiesta; immagini inline in base64/URL limitate a 32 MiB |
| Compatibilità API | Compatibile con OpenAI e Anthropic; l'endpoint Anthropic /messages richiede l'header beta files-api |
Fonte: guida ufficiale della Files API, consultata il 2026-08-21.
Carica una volta, referenzia per sempre (beh, fino a 30 giorni)
Carica uno screenshot e ottieni un file_id:
curl https://api.deepseek.com/files \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-F "purpose=user_data" \
-F "file=@dashboard.png"Poi referenzialo in una chat vision-exp — niente blob base64, nessun nuovo upload nei turni successivi:
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": "Which metric regressed in this dashboard?"},
{"type": "file", "file_id": "file-api-xxxx"}
]
}]
}'Python con l'SDK OpenAI — upload, poi chat:
from openai import OpenAI
client = OpenAI(api_key="YOUR_KEY", base_url="https://api.deepseek.com")
f = client.files.create(file=open("dashboard.png", "rb"), purpose="user_data")
resp = client.chat.completions.create(
model="deepseek-v4-flash-vision-exp",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Which metric regressed?"},
{"type": "file", "file_id": f.id},
],
}],
)
print(resp.choices[0].message.content)- Alternativa inline: un blocco file può contenere
file_data(base64) invece difile_id— campi reciprocamente esclusivi;filenamepuò accompagnare solo file_data. - Stack in stile Anthropic: gli stessi blocchi file funzionano su /messages con l'header
anthropic-beta: files-api-2025-04-14.
Quando usare i file rispetto a base64 o URL
| Metodo | Dimensione massima | Ideale per |
|---|---|---|
| base64 inline | 32 MiB | Immagini generate in-process una tantum; il metodo più semplice da implementare |
| URL esterno | 32 MiB, URL da 8.192 caratteri, recupero entro 60s | Immagini ospitate pubblicamente; nessun passaggio di upload |
| Files API | 64 MiB | Loop di screenshot per agent, immagini di riferimento ripetute, qualsiasi elemento riutilizzato tra turni |
FAQ
Ho letto che DeepSeek non ha un endpoint per i file: è una novità?
Corretto fino al 21 agosto 2026 — le guide meno recenti che indicavano "nessuna route /v1/files, estrai il testo da solo" erano accurate per l'epoca e sono ormai superate. La Files API è stata lanciata insieme al supporto vision.
Posso caricare PDF o documenti?
No — la Files API accetta attualmente solo formati immagine (JPEG/PNG/GIF/WebP). Per i PDF, renderizza le pagine come immagini lato chiamante, quindi caricale o inviale inline.
Quanto durano i file?
Tra 1 ora e 30 giorni tramite expires_after, oppure a tempo indeterminato se omesso — entro la quota di 25 GiB / 10.000 file.
I file funzionano con modelli non-vision?
I blocchi file vengono elaborati da deepseek-v4-flash-vision-exp; le normali versioni V4-Flash/V4-Pro rimangono solo testo. Non inviare riferimenti a file verso modelli testuali.