Compare Files API and Collections size limits
Compare Files API and Collections size limits
Pick the store by how you will read the file later. Files attach to chat or Imagine by file_id. Collections index documents for semantic search and RAG. Caps differ.
| Files API | Collections | |
|---|---|---|
| Max size per file | 512 MB | 100 MB |
| Primary use | Chat attachments, Imagine inputs/outputs, downloadable blobs | Persistent knowledge base with embeddings |
| Auth for upload | Team XAI_API_KEY on api.x.ai |
Upload bytes with XAI_API_KEY, attach with Management key |
| TTL | Optional expires_after (1h–30d) on upload |
Stays until you delete; needs account credits to upload |
| Search | List / get / content by id | Semantic, keyword, or hybrid search across the collection |
A 200 MB PDF belongs on Files (or outside both). A 40 MB 10-K belongs in a collection if you will search it. Same bytes can live in Files and also be linked into a collection — collections store a reference plus an embedding index, not a second product name for the same quota.
MIME expectations
Files work best with structured text, markdown, code, CSV, JSON, and PDF. Collections accept those plus many office and code MIME types (PDF, DOCX, XLSX, HTML, and a long UTF-8 text list). Collections also convert and chunk special MIME types; plain UTF-8 text still works when the type is not on the special list.
Practical picks
- Chat / tool loops with a single large blob → Files (up to 512 MB). Set a TTL if the blob is session-scoped (Set a TTL on Files API uploads).
- Many docs you will query in natural language → Collections (100 MB each). Upload path: Upload a document to a collection.
- Imagine stills and clips you will edit again → Files +
storage_options(Use the Files API with Imagine).
Pitfalls
- Pushing a collection document past 100 MB — rejected even though Files allows 512 MB.
- Expecting Collections search on a file that only exists in Files storage.
- Skipping Management API permissions when attaching to a collection.