Guías / DeepSeek Files API
DeepSeek Files API (2026): límites, subidas y file_id en la práctica
DeepSeek lanzó discretamente su primer endpoint de archivos el 21 de agosto de 2026, junto con el modelo de visión, lo que deja obsoletas muchas guías anteriores (varias todavía afirman que la API de DeepSeek "no tiene ruta de subida de archivos"). Esta guía incluye los límites verificados, ejemplos de subida y referencia en curl y Python, y cuándo usar archivos en lugar de base64.
La DeepSeek Files API sube una imagen una sola vez y devuelve un file_id al que haces referencia en el chat.
Sube con purpose="user_data"; un archivo puede tener hasta 64 MiB (ventana de subida de 10 minutos); el almacenamiento es de 25 GiB / 10,000 archivos por usuario; retención de 1 hora a 30 días o permanente sin expires_after.
Haz referencia a archivos desde chats de deepseek-v4-flash-vision-exp mediante un bloque {"type":"file","file_id":...} — las imágenes con file_id pueden ser de 64 MiB en una solicitud frente a 32 MiB inline. Desde el endpoint compatible con Anthropic, añade el encabezado anthropic-beta: files-api-2025-04-14.
Límites de un vistazo
| Límite | Valor (documentación oficial, 2026-08-21) |
|---|---|
| Formatos | JPEG, PNG, GIF, WebP — detectados por el contenido del archivo, no por la extensión |
| Por archivo | Máx. 64 MiB; la subida debe completarse en 10 minutos |
| Por usuario | 25 GiB de almacenamiento; 10,000 archivos guardados |
| Retención | De 1 hora a 30 días, o permanente (omitiendo expires_after) |
| Purpose | Debe ser user_data (único purpose admitido, también para filtrar listas) |
| Tamaño en la solicitud | Imagen por file_id de hasta 64 MiB por solicitud; imágenes base64/URL inline limitadas a 32 MiB |
| Compatibilidad de la API | Compatible con OpenAI y compatible con Anthropic; /messages de Anthropic requiere el encabezado beta files-api |
Fuente: guía oficial de Files API, consultada el 2026-08-21.
Sube una vez, referencia para siempre (bueno, hasta 30 días)
Sube una captura de pantalla y obtén un file_id:
curl https://api.deepseek.com/files \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-F "purpose=user_data" \
-F "file=@dashboard.png"Luego haz referencia a ella en un chat de vision-exp — sin blob base64 ni necesidad de resubir en turnos posteriores:
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 el SDK de OpenAI — subir y luego chatear:
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 bloque de archivo puede llevar
file_data(base64) en lugar defile_id— campos mutuamente excluyentes;filenamesolo puede acompañar a file_data. - Stack estilo Anthropic: los mismos bloques de archivo funcionan en /messages con el encabezado
anthropic-beta: files-api-2025-04-14.
Cuándo usar archivos vs base64 vs URL
| Método | Tamaño máx. | Ideal para |
|---|---|---|
| base64 inline | 32 MiB | Imágenes puntuales generadas durante la ejecución; lo más simple de programar |
| URL externa | 32 MiB, URL de 8,192 caracteres, obtención en 60 s | Imágenes alojadas públicamente; sin ningún paso de subida |
| Files API | 64 MiB | Bucles de capturas de agentes, imágenes de referencia recurrentes, todo lo que se reutilice entre turnos |
FAQ
Leí que DeepSeek no tiene endpoint de archivos, ¿es esto nuevo?
Correcto hasta el 21 de agosto de 2026: las guías anteriores que describían "sin ruta /v1/files, extrae el texto tú mismo" eran precisas en su momento y ahora están desactualizadas. La Files API se lanzó con el estreno de los modelos de visión.
¿Puedo subir archivos PDF o documentos?
No: la Files API actualmente solo admite formatos de imagen (JPEG/PNG/GIF/WebP). Para archivos PDF, renderiza las páginas como imágenes en el cliente y luego súbelas o insértalas inline.
¿Cuánto tiempo se conservan los archivos?
Entre 1 hora y 30 días mediante expires_after, o permanentes si lo omites, dentro de tu cuota de 25 GiB / 10,000 archivos.
¿Funcionan los archivos con modelos que no son de visión?
Los bloques de archivo son procesados por deepseek-v4-flash-vision-exp; las versiones estándar V4-Flash/V4-Pro siguen siendo solo de texto. No apuntes referencias de archivos a modelos de texto.