anthropics_skills/skills/claude-api/python/claude-api/files-api.md

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

The file argument accepts a (filename, content, content_type) tuple, a pathlib.Path (or any PathLike — read for you, async-safe with AsyncAnthropic), or an open binary file object.

import anthropic
from pathlib import Path

client = anthropic.Anthropic()

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

---

Use a File in Messages

PDF / Text Document

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    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"],
)
for block in response.content:
    if block.type == "text":
        print(block.text)

Image

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    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

Iterate the list result directly — the SDK auto-paginates across all pages. Only use .data if you want the first page only.

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

Get File Metadata

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

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).

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:

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="claude-opus-4-8",
        max_tokens=16000,
        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}")
    text = next((b.text for b in response.content if b.type == "text"), "")
    print(f"A: {text[:200]}")

# 3. Clean up when done
client.beta.files.delete(uploaded.id)