Claude Files API Python Example

Use the Anthropic Files API in Python to upload documents once and reference them in multiple Claude requests. Reduces costs by avoiding repeated base64 encoding of large files.

The Anthropic Files API lets you upload a document once and reference it across many Claude requests using a file_id. This is especially useful for document Q&A apps, code review tools, or any workflow that processes the same file repeatedly.

Installation

pip install anthropic  # Files API included in SDK ≥ 0.34

Upload a file

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env

# Upload a PDF
with open("quarterly_report.pdf", "rb") as f:
    file_obj = client.beta.files.upload(
        file=("quarterly_report.pdf", f, "application/pdf"),
    )

file_id = file_obj.id
print(f"Uploaded: {file_id}")
# file_id: file_01ABC123...

Reference the file in a Claude request

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": file_id,
                    }
                },
                {
                    "type": "text",
                    "text": "Summarize the key financial highlights from this report in 5 bullet points."
                }
            ]
        }
    ],
    betas=["files-api-2025-04-14"],
)

print(response.content[0].text)

Reuse the same file across multiple requests

questions = [
    "What was the revenue growth year-over-year?",
    "Which product line had the highest margin?",
    "What risks did management highlight?",
]

for question in questions:
    resp = client.beta.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "document", "source": {"type": "file", "file_id": file_id}},
                    {"type": "text", "text": question}
                ]
            }
        ],
        betas=["files-api-2025-04-14"],
    )
    print(f"Q: {question}")
    print(f"A: {resp.content[0].text}\n")

List uploaded files

files = client.beta.files.list()
for f in files.data:
    print(f.id, f.filename, f.size, f.created_at)

Delete a file when done

client.beta.files.delete(file_id)
print("File deleted")

Upload an image file

with open("diagram.png", "rb") as f:
    img_file = client.beta.files.upload(
        file=("diagram.png", f, "image/png"),
    )

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "file",
                        "file_id": img_file.id,
                    }
                },
                {"type": "text", "text": "Describe the architecture shown in this diagram."}
            ]
        }
    ],
    betas=["files-api-2025-04-14"],
)

Files API vs base64 inline — when to use each

Supported file types

Files are retained for 30 days after last access. For cost estimation across document Q&A workflows, use the Claude API Cost Calculator. For PDF analysis patterns, see the PDF analysis guide and vision API example.

Frequently asked questions

Free tools

More examples