Files API — Python

The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.

Beta: Pass `betas=["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).

Key Facts

Maximum file size: 500 MB
Total storage: 100 GB per organization
Files persist until deleted
File operations (upload, list, delete) are free; content used in messages is billed as input tokens
Not available on Amazon Bedrock or Google Vertex AI

Upload a File

```python import anthropic

client = anthropic.Anthropic()

uploaded = client.beta.files.upload( file=("report.pdf", open("report.pdf", "rb"), "application/pdf"), ) print(f"File ID: {uploaded.id}") print(f"Size: {uploaded.size_bytes} bytes") ```

Use a File in Messages

PDF / Text Document

```python response = client.beta.messages.create( model="{{OPUS_ID}}", max_tokens=1024, messages=[{ "role": "user", "content": [ {"type": "text", "text": "Summarize the key findings in this report."}, { "type": "document", "source": {"type": "file", "file_id": uploaded.id}, "title": "Q4 Report", # optional "citations": {"enabled": True} # optional, enables citations } ] }], betas=["files-api-2025-04-14"], ) print(response.content[0].text) ```

Image

```python image_file = client.beta.files.upload( file=("photo.png", open("photo.png", "rb"), "image/png"), )

response = client.beta.messages.create( model="{{OPUS_ID}}", max_tokens=1024, messages=[{ "role": "user", "content": [ {"type": "text", "text": "What's in this image?"}, { "type": "image", "source": {"type": "file", "file_id": image_file.id} } ] }], betas=["files-api-2025-04-14"], ) ```

Manage Files

List Files

```python files = client.beta.files.list() for f in files.data: print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)") ```

Get File Metadata

```python file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w") print(f"Filename: {file_info.filename}") print(f"MIME type: {file_info.mime_type}") ```

Delete a File

```python client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w") ```

Download a File

Only files created by the code execution tool or skills can be downloaded (not user-uploaded files).

```python file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w") file_content.write_to_file("output.txt") ```

Full End-to-End Example

Upload a document once, ask multiple questions about it:

```python import anthropic

client = anthropic.Anthropic()

1. Upload once

uploaded = client.beta.files.upload( file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"), ) print(f"Uploaded: {uploaded.id}")

2. Ask multiple questions using the same file_id

questions = [ "What are the key terms and conditions?", "What is the termination clause?", "Summarize the payment schedule.", ]

for question in questions: response = client.beta.messages.create( model="{{OPUS_ID}}", max_tokens=1024, messages=[{ "role": "user", "content": [ {"type": "text", "text": question}, { "type": "document", "source": {"type": "file", "file_id": uploaded.id} } ] }], betas=["files-api-2025-04-14"], ) print(f"\nQ: {question}") print(f"A: {response.content[0].text[:200]}")

3. Clean up when done

client.beta.files.delete(uploaded.id) ```

4.0 KiB Raw Blame History