Supported File Types in OpenAI APIs: Full Guide with Limits and Use Cases

## Overview of File Support in OpenAI Ecosystems OpenAI's APIs handle a wide array of file types to enable diverse applications like data analysis, document processing, model customization, and image understanding. Understanding these supports is crucial for developers integrating features such as Assistants with Code Interpreter or Retrieval tools, fine-tuning custom models, or leveraging vision capabilities. This guide breaks down supported formats by API/component, compares them side-by-side, highlights key limits, and provides actionable examples to ensure smooth implementation. File handling varies based on the use case: code execution requires executable-like formats, retrieval needs searchable documents, fine-tuning demands structured data, and vision focuses on images. All files must adhere to size and token limits to prevent rejection—typically 512 MB per file and a 2 million token cap for text-based processing (with exceptions for images). ## Comparison of Supported File Types Across OpenAI Features To make selection straightforward, here's a breakdown table comparing formats: | Feature | Supported Extensions | Key Notes & Limits | |--------------------------|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------| | **Assistants API (Code Interpreter & Retrieval)** | .c, .cs, .cpp, .csv, .doc, .docx, .html, .java, .json, .md, .pdf, .php, .pptx, .py, .rb, .sh, .sql, .ts, .txt, .xlsx, .xml, .zip | Up to 20 files per assistant; .zip limited to single text/code file (e.g., .md/.py); 512 MB/file; total <20 GB/assistant. | | **Files API (General)** | .c, .cs, .cpp, .csv, .docx, .html, .java, .json, .md, .pdf, .php, .pptx, .py, .rb, .sh, .sql, .ts, .txt, .xlsx, .xml, .zip | Used for Assistants, fine-tuning prep, Batch; 512 MB/file, 2M tokens (images 20 MB for FT). | | **Fine-tuning** | Text: .jsonl, .json, .txt<br>Images: .png, .jpg, .jpeg | .jsonl required for chat/vision FT; images ≤20 MB; precise JSONL formatting essential. | | **Batch API** | Same as Files API: .c, .cs, .cpp, .csv, .docx, .html, .java, .json, .md, .pdf, .php, .pptx, .py, .rb, .sh, .sql, .ts, .txt, .xlsx, .xml, .zip | For async large-scale jobs; inherits Files API limits. | | **Vision Models (Chat Completions)** | .png, .jpg, .jpeg, .gif, .webp | ≤20 MB/image; base64 or URL; no token limit but resolution affects processing. | This table reveals overlaps (e.g., documents like .pdf/.docx everywhere except pure fine-tuning text) and specialties (e.g., images only for FT/vision). Always verify via API docs for updates. ## Deep Dive: Assistants API and Code Interpreter Tool The Assistants API shines for interactive apps, powering tools like Code Interpreter (for running Python/R code on uploaded data) and Retrieval (for RAG over documents). Supported formats cater to code, data, and docs: - **Code files** (.py, .js/.ts, .java, .cpp, etc.): Execute snippets directly. - **Data** (.csv, .xlsx): Analyze spreadsheets or tables. - **Documents** (.pdf, .docx, .pptx): Extract text for querying. - **Archives** (.zip): Bundle related files, but strictly one folder with one eligible file inside—no nested zips or multiples. **Limits**: 512 MB/file; assistants capped at 20 files (to manage context); total storage <20 GB. Tokenization counts toward the model's context window. **Practical Example**: Upload a sales .csv for trend analysis. ```python # Python SDK example import openai client = openai.OpenAI(api_key="your-key") file = client.files.create( file=open("sales_data.csv", "rb"), purpose="assistants" ) assistant = client.beta.assistants.create( name="Data Analyst", instructions="Analyze the CSV for trends.", tools=[{"type": "code_interpreter"}], file_ids=[file.id] ) ``` Real-world: A finance app uploads .xlsx reports; the assistant generates charts via matplotlib in Code Interpreter. **Tip**: Pre-compress large .zip datasets, but test unzipping logic. ## Files API: The Backbone for Uploads The Files API is your entry point for persistent storage, supporting the broadest range for downstream uses. It mirrors Assistants formats but enables fine-tuning prep and Batch jobs. **Use Cases**: - Store .json/.csv for batch processing. - Prep .pdf/.md for retrieval-augmented generation. **Limits**: Identical to Assistants—512 MB, 2M tokens. List/retrieve/delete via API. **Example CURL Upload**: ```bash curl https://api.openai.com/v1/files \\ -H "Authorization: Bearer $OPENAI_API_KEY" \\ -F purpose="fine-tune" \\ -F file="@mydata.jsonl" ``` This returns a file ID for referencing elsewhere. ## Fine-Tuning: Specialized Formats and Requirements Customizing models requires precise data: - **Text-based**: .jsonl (preferred, with `messages` format), .json, .txt. - Each line: `{"messages": [{"role": "user", "content": "query"}, {"role": "assistant", "content": "response"}]}` - **Vision Fine-Tuning**: Pair .jsonl with .png/.jpg/.jpeg images referenced by `image_url`. **Limits**: 512 MB text files, 20 MB images. Train/validation splits mandatory. **Example JSONL Snippet**: ```jsonl {"messages": [{"role": "user", "content": [{"type": "text", "text": "Describe this image."}, {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}]}, {"role": "assistant", "content": "A cat on a mat."}]} ``` **Pro Tip**: Use OpenAI's data prep tools; validate JSONL with `openai tools fine_tunes.prepare_data`. Real-world: Train a support bot on .jsonl chat logs or a vision model on product defect images. ## Batch API: Scaling with File Inputs For cost-efficient, async processing of large inputs, Batch API uses Files API formats. Upload inputs as .jsonl or docs, process in bulk (e.g., 50k+ prompts). **Benefits**: 50% cheaper, 24h turnaround. **Workflow**: Upload file → create batch → poll results. ## Vision Models: Image-Only Support GPT-4o and similar handle images in Chat Completions API: - Formats: .png, .jpg, .jpeg, .gif, .webp. - Max 20 MB; supports detail levels (low/auto/high). **Example**: ```python response = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": [{"type": "text", "text": "What's in this image?"}, {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}]}] ) ``` Applications: OCR on scanned .pdfs (convert pages to .jpg), meme analysis. ## Best Practices and Common Pitfalls - **Token Estimation**: Use tiktoken library: `encoding.encode(file.read())` → len(tokens). - **Error Handling**: Unsupported formats return 400; check `purpose` matches (e.g., "assistants" vs "fine-tune"). - **Optimization**: Split large files; convert .doc to .txt if needed. - **Security**: No executables in .zip—OpenAI sandboxes Code Interpreter. - **Scaling**: For >20 GB, use multiple assistants or Batch. By mastering these, you'll build robust apps—from document Q&A to custom vision models—without upload failures. Monitor API changelog for expansions like potential audio support. (Word count: ~1050) --- <div style="text-align: center; margin-top: 2rem;"> <a href="https://help.openai.com/en/articles/8983675-what-types-of-files-are-supported" target="_blank" rel="noopener noreferrer" class="view-full-resource-btn" style="display: inline-block; background-color: #f97316; color: white; padding: 12px 24px; border-radius: 8px; text-decoration: none; font-weight: 600; transition: background-color 0.2s;">View Full Resource</a> </div>