DeepSeek Files API: image uploads, 64 MiB limit, storage, expiration, and file IDs
Updated: 3 days ago
DeepSeek now has a public Files API, but its current scope is narrower and more precise than the phrase 'file upload' suggests. The endpoint stores image files that can later be referenced by file_id in requests to deepseek-flash. It is designed to avoid repeated uploads and to handle images that are inconvenient to send inline; it is not a general-purpose document repository for PDF, DOCX, XLSX, or arbitrary attachments.
The published limits are unusually concrete: JPEG, PNG, GIF, and WebP; 64 MiB per uploaded file; 25 GiB of stored files per user; up to 10,000 stored files; and optional expiration from one hour to 30 days, with permanent storage when expiration fields are omitted.
··········
THE FILES API STORES IMAGES AND RETURNS A REUSABLE FILE ID
An upload is sent to the Files API with purpose set to user_data. DeepSeek returns an identifier in the file-api-... form. That identifier can then be referenced inside a chat request instead of resending the binary image. The file belongs to the API key that created it and can be listed, inspected, reused, or deleted.
........
Files API limit | Current value |
|---|---|
Supported formats | JPEG, PNG, GIF, WebP |
Maximum file size | 64 MiB |
Maximum stored files | 10,000 |
Maximum storage | 25 GiB |
Filename length | 512 characters |
Optional expiration | 1 hour to 30 days; omit for permanent |
........
··········
A FILE ID CHANGES BANDWIDTH AND STORAGE, NOT THE MODEL'S VISION COST
The main efficiency gain is transport. Upload once, then reuse the returned ID across requests. The image still becomes model input when referenced, so image tokens are still billed with the request. A file_id therefore reduces repeated network transfer and request-body pressure; it does not make repeated inference free.
Data Studios example: if a 20 MiB image is used in 50 independent requests, inline delivery can move roughly 1,000 MiB of source image data before encoding overhead. Uploading it once and reusing file_id reduces that repeated client-to-API transfer dramatically, even though each inference still processes the image.
··········
THE 25 GIB STORAGE LIMIT IS SEPARATE FROM THE 64 MIB REQUEST LIMIT
Storage capacity and per-file capacity solve different constraints. At the absolute 64 MiB maximum, 25 GiB corresponds to about 400 such files before storage is exhausted. In practice the 10,000-file count ceiling becomes the tighter constraint when average images are smaller than roughly 2.6 MiB.
........
Average stored image | Approx. files before 25 GiB | Which ceiling tends to bind first |
|---|---|---|
1 MiB | ~25,600 | 10,000-file count |
2.5 MiB | ~10,240 | Nearly equal |
10 MiB | ~2,560 | 25 GiB storage |
64 MiB | ~400 | 25 GiB storage |
........
··········
EXPIRATION CAN BE SET PER FILE OR OMITTED FOR PERMANENT STORAGE
When expiration is supplied, DeepSeek accepts a lifetime between 3,600 and 2,592,000 seconds: one hour through 30 days. Omitting the expiration fields keeps the uploaded file available without that scheduled expiry. Applications that handle temporary screenshots or sensitive intermediate assets should set explicit lifetimes instead of accumulating permanent files by default.
··········
THE FILES API IS CURRENTLY FREE TO USE, BUT INFERENCE IS STILL METERED
DeepSeek introduced the Files API as free infrastructure for storing and reusing supported images. The subsequent model request remains normal API usage: text and image tokens are processed and billed according to the model pricing rules. 'Free Files API' therefore refers to the storage/upload mechanism, not to free multimodal inference.
··········
OPENAI-COMPATIBLE AND ANTHROPIC-COMPATIBLE FILE ENDPOINTS HAVE DIFFERENT RESPONSE SHAPES
DeepSeek exposes file operations through both compatibility families. The underlying purpose is the same, but pagination fields, timestamp formats, object fields, and headers differ. Integrations should follow the schema of the compatibility layer they actually use rather than assuming the two responses are interchangeable.
··········
USE THE FILES API WHEN AN IMAGE WILL BE REUSED OR IS TOO LARGE FOR INLINE DELIVERY
For a one-off small image, base64 or a public image URL can be simpler. Files API becomes attractive when the same asset appears repeatedly, when request bodies become large, or when an image exceeds the inline 32 MiB per-image ceiling but remains within the 64 MiB file_id limit.
··········
FOLLOW US FOR MORE
··········
DATA STUDIOS
··········
datastudios.org
