Files APIs: Reusing Uploads Across Claude, GPT, and Gemini
Compare Files API mechanics across Anthropic, OpenAI, and Google: lifecycle limits, request shapes, access scoping, and implementation best practices.
- Anthropic scopes file IDs to entire workspaces, requiring distinct workspaces for multi-tenant isolation.
- OpenAI accepts file IDs, direct Base64 payloads, or external file URLs in its Responses API with configurable PDF image detail levels.
- Google Gemini stores uploaded media without fees for 48 hours, supporting files up to 2 GB with a 20 GB project cap.
- Uploaded files cannot be directly downloaded by users on Anthropic or Gemini; downloads are reserved for model-generated artifacts.
Architectural Differences: Upload-Once Storage Versus Inline Payloads
Passing large binary files, documents, and media assets repeatedly inside API prompt payloads introduces unnecessary network transfer latency and application complexity. Dedicated file storage endpoints allow developers to upload an asset a single time and reuse it across multiple completion requests by passing a persistent identifier or URI.
Anthropic, OpenAI, and Google each implement distinct lifecycle, scoping, and input conventions for uploaded assets. Anthropic uses workspace-scoped uploads referenced by file_id inside standard content blocks. OpenAI provides file management through its Files API with a dedicated purpose flag, referencing artifacts via file_id inside the Responses API and Chat Completions. Google Gemini offers a dedicated media storage layer that generates a resource URI referenced in Interactions API requests, holding data temporarily at no storage charge. For teams calculating prompt payload costs across these workflows, see the /tools/llm-api-cost-calculator/ and the guide on /posts/pdf-and-document-input-in-claude-gpt-and-gemini/.
Anthropic Files API: Workspace Boundaries and Content Blocks
The Anthropic Files API is generally available across the Claude API, Claude Platform on AWS, and Microsoft Foundry (requiring a Hosted on Anthropic deployment). It follows a create-once, reference-many pattern where uploaded assets produce a unique identifier starting with file_. Once stored, user-uploaded files cannot be downloaded back via the API; file downloads are restricted to artifacts generated downstream by skills or the code execution tool.
A critical security constraint of the Claude Files API is resource scoping: files are scoped to the entire workspace rather than an individual session or user. Any API key belonging to a workspace can access all files stored within that workspace. For multi-tenant architectures, applications must establish hard isolation by creating separate workspaces (supported up to 100 workspaces per organization). Untrusted end-user input must never dictate the file_id passed to the API.
FILE_ID=$(curl -X POST https://api.anthropic.com/v1/files \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-F "file=@/path/to/document.pdf" | jq -r '.id')
curl -X POST https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "Please summarize this document for me."},
{"type": "document", "source": {"type": "file", "file_id": "'"$FILE_ID"'"}}
]
}
]
}'
Claude consumes referenced files through specific content block types based on format: document blocks for application/pdf and text/plain, image blocks for JPEG, PNG, GIF, and WEBP formats, and container_upload blocks when feeding raw files into the code execution environment. File listing via /v1/files is paginated, defaulting to 20 items and returning at most 1,000 files per page, ordered newest first.
OpenAI Responses API: Multi-Mode File Inputs and Processing Controls
OpenAI supports file inputs across two primary endpoints: the Responses API and Chat Completions. Chat Completions limits file input exclusively to PDF documents supplied via Base64 or uploaded file_id. The Responses API accepts a much broader spectrum of formats including PDFs, rich text documents (.doc, .docx, .rtf, .odt), presentations (.ppt, .pptx), plain text or code, and spreadsheets (.csv, .xls, .xlsx).
Files can be delivered into the Responses API using three different input properties: file_data for inline Base64 strings, file_url for external HTTP links, or file_id pointing to files uploaded to /v1/files with the purpose parameter set to user_data.
curl https://api.openai.com/v1/files \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F purpose="user_data" \
-F file="@draconomicon.pdf"
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"input": [
{
"role": "user",
"content": [
{
"type": "input_file",
"file_id": "file-6F2ksmvXxt4VdoqmHRw6kL"
},
{
"type": "input_text",
"text": "What is the first dragon in the book?"
}
]
}
]
}'
Processing behavior varies significantly by file format within the Responses API. For PDF files on vision-capable models (such as gpt-4o and later), the endpoint extracts text and renders page images. Image processing granularity is governed by an optional detail setting (auto, low, or high). In GPT-5.6 and later models, auto defaults to high, whereas older models default to low. Non-PDF rich documents only extract text, discarding embedded charts or diagrams unless the source is converted to PDF before submission. For spreadsheets, the engine parses up to the first 1,000 rows per sheet, augmenting the input with structural metadata and headers.
Gemini Files API: Free Temporary Storage and Media URIs
Google provides the Gemini Files API as a zero-cost utility for uploading media assets prior to inference across all regions where the Gemini API is offered. The Files API is mandatory whenever total request payloads exceed 100 MB, or when standalone PDF inputs exceed 50 MB. Projects can retain up to 20 GB of files concurrently, with individual files supporting sizes up to 2 GB.
Unlike Anthropic’s persistent workspace files, Gemini imposes an automatic lifecycle: all uploaded files are stored for 48 hours and then deleted automatically. Developers can query file metadata with files.get, view all stored items using files.list, or remove them early using files.delete. User-uploaded files cannot be re-downloaded, though model-generated media outputs can be retrieved using files.download.
from google import genai
client = genai.Client()
myfile = client.files.upload(file="path/to/sample.mp3")
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{"type": "text", "text": "Describe this audio clip"},
{"type": "audio", "uri": myfile.uri, "mime_type": myfile.mime_type}
]
)
print(interaction.output_text)
When submitting inference requests to interactions.create with models like gemini-3.8-flash, files are passed using their generated resource uri alongside the corresponding MIME type. This supports multimodal inputs including audio, video, images, and text documents without packing large binary chunks into the request body.
Cross-Provider Files API Feature and Limit Comparison
Understanding the precise technical parameters and retention mechanics across providers prevents architectural errors, unintended payload rejections, and tenant data leaks.
| Feature / Limit | Anthropic Claude | OpenAI Responses | Google Gemini |
|---|---|---|---|
| Upload Mechanism | POST /v1/files multipart form | POST /v1/files with purpose | Resumable /v1beta/files upload |
| Reference Key in Invocations | file_id in source object | file_id in input_file | uri in content block |
| File Retention Window | Indefinite (expires_at null) | Persistent until deleted | 48 hours (auto-deleted) |
| Storage Billing | No separate storage fee | Standard Files storage | Available at no cost |
| Size Limits | Controlled by model context | Varies by endpoint | 2 GB per file / 20 GB per project |
| Mandatory Threshold | Optional reuse mechanism | Optional reuse mechanism | > 100 MB total (> 50 MB for PDFs) |
| User Asset Download | Downloadable false | Managed via Files API | Not supported for user uploads |
| Isolation Boundary | Workspace (up to 100/org) | Project / Organization | Project scoped |
| Supported Model Examples | claude-opus-5-5, claude-sonnet-5.5 | gpt-6-astra, gpt-5.6-sol | gemini-3.8-flash, gemini-2.5-pro |
For ongoing token pricing related to document analysis across these platforms, refer to /tools/llm-api-pricing/ and review guidelines in /posts/rate-limits-and-usage-tiers-at-anthropic-openai-and-google/.
Implementation Checklist and Architectural Gotchas
When integrating file uploads across providers, teams should structure their client libraries and ingestion workflows around several operational considerations:
- Never allow user-supplied file identifiers directly into message payloads: In Anthropic, any key in a workspace can resolve any
file_idin that workspace. Track internal tenant ownership mappings strictly in your application database. - Account for Gemini’s 48-hour expiration: Do not store Gemini file URIs as permanent asset pointers in long-term databases. Re-upload or synchronize source files if calls occur outside the 48-hour window.
- Pre-convert office documents with visual elements to PDF: OpenAI Responses and Anthropic do not extract embedded charts or graphics from
.docxor presentation formats directly. Rendering to PDF preserves visual fidelity for vision-capable models. - Select appropriate PDF detail levels on OpenAI: Use
lowdetail oninput_fileitems to reduce input tokens when documents are primarily text, or rely onhigh(the default forautoon GPT-5.6 and later) for dense technical charts. - Observe spreadsheet row truncations: OpenAI augments spreadsheets but truncates extraction at 1,000 rows per sheet. Heavy data tasks require code execution or dedicated shell environments rather than raw file prompts.