Files API, vision & PDF

1 · Two ways to give Claude a file essential

Claude can read images and PDFs, not just text. There are exactly two ways to hand it a file, and everything in this lesson is a variation on one of them. Inline: you put the raw bytes (base64-encoded) directly inside the message as a content block — one self-contained request. Files API: you upload the file once, get back a file_id, and then reference that id in as many messages as you like — the bytes are stored on Anthropic's side and never re-sent.

The message body is the same shape either way. A user message's content is a list of blocks. For a picture you send an {"type": "image", ...} block; for a PDF or text file you send an {"type": "document", ...} block; and you usually add a {"type": "text", ...} block with your question. The only thing that changes between the two paths is the block's source: raw base64 bytes inline, versus a {"type": "file", "file_id": ...} reference.

Read the two diagrams together: the top one uploads the bytes on every call; the bottom one uploads once and then passes a small id string forever after. Same picture reaching Claude — very different network and cost profile when you ask more than one question.

2 · Recipe: an image as inline base64 essential

The most direct way to send a picture: read the file, base64-encode the bytes, and put them in an image block whose source.type is "base64". You must tell the API the media_type (e.g. image/png, image/jpeg, image/gif, image/webp). This block is REAL SDK code — it opens a real file and calls the API.

image_inline.py# needs: pip install anthropic + ANTHROPIC_API_KEY (+ a real image/PDF file)
import base64
import anthropic

client = anthropic.Anthropic()   # reads ANTHROPIC_API_KEY from the environment

with open("chart.png", "rb") as f:
    image_b64 = base64.standard_b64encode(f.read()).decode("utf-8")

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "base64",
                    "media_type": "image/png",   # match the actual file type
                    "data": image_b64,
                },
            },
            {"type": "text", "text": "What trend does this chart show?"},
        ],
    }],
)
print(next(b.text for b in resp.content if b.type == "text"))

3 · See the block shape — offline essential

Before spending a single token, it helps to see what an image content block actually is: a plain Python dict. The helper below takes raw bytes and a media type, base64-encodes them with the standard library, and builds the exact block the SDK sends. It uses a tiny hardcoded PNG byte literal so it needs no file, no key, and no network — it just prints the block's shape. This is the one recipe on the page you can run right now.

block_shape.pyimport base64

# A tiny hardcoded PNG (the 1x1 transparent pixel) — no file needed.
PNG_BYTES = (
    b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR"
    b"\x00\x00\x00\x01\x00\x00\x00\x01\x08\x06"
)

def image_block(raw: bytes, media_type: str) -> dict:
    """Build the inline base64 image content block the SDK would send."""
    b64 = base64.standard_b64encode(raw).decode("utf-8")
    return {
        "type": "image",
        "source": {"type": "base64", "media_type": media_type, "data": b64},
    }

block = image_block(PNG_BYTES, "image/png")
print("type:        ", block["type"])
print("source.type: ", block["source"]["type"])
print("media_type:  ", block["source"]["media_type"])
print("data length: ", len(block["source"]["data"]), "base64 chars")
print("data preview:", block["source"]["data"][:16], "...")

type:         image
source.type:  base64
media_type:   image/png
data length:  36 base64 chars
data preview: iVBORw0KGgoAAAAN ...

4 · Recipe: a PDF document & document Q&A intermediate

PDFs use a document block instead of an image block, with media_type: "application/pdf". Claude reads both the text and the visual layout of each page — tables, charts, signatures — so you can ask questions that depend on how the page looks, not just its extracted text. Put the document block before your question text. This is REAL SDK code.

pdf_inline.py# needs: pip install anthropic + ANTHROPIC_API_KEY (+ a real image/PDF file)
import base64
import anthropic

client = anthropic.Anthropic()

with open("contract.pdf", "rb") as f:
    pdf_b64 = base64.standard_b64encode(f.read()).decode("utf-8")

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_b64,
                },
            },
            {"type": "text", "text": "What is the termination clause? Quote it."},
        ],
    }],
)
print(next(b.text for b in resp.content if b.type == "text"))

5 · Recipe: upload once, reuse with the Files API intermediate

The Files API is the answer to "I have one document and twenty questions". You upload the file once and get back a file_id. Every later message references that id via a {"type": "file", "file_id": ...} source — the bytes never travel again. The Files API is beta, so you call it on the client.beta.* namespace and pass betas=["files-api-2025-04-14"] on both the upload and any messages.create that references the file. This is REAL SDK code.

files_api.py# needs: pip install anthropic + ANTHROPIC_API_KEY (+ a real image/PDF file)
import anthropic

client = anthropic.Anthropic()

# 1. Upload ONCE. The file argument is a (filename, fileobj, media_type) tuple.
uploaded = client.beta.files.upload(
    file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
    betas=["files-api-2025-04-14"],
)
print("file_id:", uploaded.id, "| size:", uploaded.size_bytes, "bytes")

# 2. Reference the SAME file_id across many calls — bytes never re-sent.
questions = [
    "What are the key terms?",
    "What is the termination clause?",
    "Summarize the payment schedule.",
]
for q in questions:
    resp = client.beta.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": [
                {"type": "document", "source": {"type": "file", "file_id": uploaded.id}},
                {"type": "text", "text": q},
            ],
        }],
        betas=["files-api-2025-04-14"],
    )
    answer = next(b.text for b in resp.content if b.type == "text")
    print(f"\nQ: {q}\nA: {answer[:120]}")

# 3. Manage stored files. Uploads count against a per-org storage quota.
for f in client.beta.files.list(betas=["files-api-2025-04-14"]):
    print(f.id, f.filename, f.size_bytes)

# 4. Clean up when you're done with it.
client.beta.files.delete(uploaded.id, betas=["files-api-2025-04-14"])

6 · Inline vs Files API — choosing advanced

Both paths get the same bytes to Claude. The decision is about how many times you'll ask and how big the file is:

Rule of thumb: inline for a one-shot (extract a field from this one receipt), Files API when the same document drives many turns (a contract you'll interrogate across a conversation, or a reference doc shared by a batch of requests). The Files API also lets a big file exceed the 32 MB inline request cap, since the bytes aren't part of the message.

7 · Recipe: citations that point at the source advanced

For document Q&A you often want the answer to cite where it came from — which page, which sentence. Set citations: {"enabled": True} on the document block. Claude then splits its reply into multiple text blocks, and blocks that draw on the document carry a citations array — each citation names the source, the cited text, and a location (a page number for PDFs, a character range for plain text). This is REAL SDK code.

citations.py# needs: pip install anthropic + ANTHROPIC_API_KEY (+ a real image/PDF file)
import base64
import anthropic

client = anthropic.Anthropic()

with open("report.pdf", "rb") as f:
    pdf_b64 = base64.standard_b64encode(f.read()).decode("utf-8")

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {"type": "base64", "media_type": "application/pdf", "data": pdf_b64},
                "title": "Q4 Report",
                "citations": {"enabled": True},   # turn citations on
            },
            {"type": "text", "text": "What were Q4 revenues? Cite the page."},
        ],
    }],
)

for block in resp.content:
    if block.type != "text":
        continue
    print(block.text)
    for c in (block.citations or []):
        # PDF citations carry a page_location; plain text carries char indices.
        print(f'   ↳ cited "{c.cited_text[:50]}" from {c.document_title}')

8 · Cost, limits & production hygiene professional

Images and documents are billed as input tokens — a page or an image costs roughly what its visual complexity works out to, and a full-resolution image can be thousands of tokens. That means the recurring cost lever is how often you re-send the same bytes. The production checklist:

Production checklist for files & vision

1. Don't re-inline. If a document is used more than once, upload it via the Files API and pass the file_id — you stop paying to ship the bytes each call.
2. Cache big prefixes. Combine the Files API with cache_control so a large reused document is neither re-uploaded nor re-tokenized (see AP2).
3. Downsample when you can. A smaller image is fewer input tokens; send the resolution the task actually needs, not the original camera dump.
4. Mind the quotas. Files API storage is capped per organization (100 GB) and individual files up to 500 MB — track what you upload.
5. Clean up. Uploaded files persist until you delete them. Delete files you no longer need so storage doesn't creep and stale documents don't linger.
6. Count before you send. Use token counting (see AP4) on representative files to budget cost before rolling out.

9 · Tech-lead — a document-ingestion contract tech-lead

A lead owns the document-handling policy for the whole system, not just one call site. That means a written contract: which paths inline vs upload (a size/reuse threshold, not per-developer whim); a file lifecycle (who uploads, who deletes, what the retention window is) so the org quota never becomes an incident; a citation requirement for any answer users act on, so claims are traceable to the source page; and a cost model that accounts for image/document input tokens and the caching + Files-API levers that reduce them.

Every mechanic in this lesson maps to one clause of that contract. The inline vs Files API table is the routing rule; the cleanup step is the lifecycle; citations are the traceability requirement; token cost is the budget. A lead makes these decisions once, writes them down, and lets the codebase follow the contract instead of re-litigating "inline or upload?" on every PR.

import base64, anthropic
client = anthropic.Anthropic()

with open("chart.png", "rb") as f:
    data = base64.standard_b64encode(f.read()).decode("utf-8")

resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=512,
    messages=[{"role": "user", "content": [
        {"type": "image", "source": {
            "type": "base64", "media_type": "image/png", "data": data}},
        {"type": "text", "text": "What does this chart show?"},
    ]}],
)
print(next(b.text for b in resp.content if b.type == "text"))

import base64, anthropic
client = anthropic.Anthropic()

with open("report.pdf", "rb") as f:
    pdf = base64.standard_b64encode(f.read()).decode("utf-8")

resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024,
    messages=[{"role": "user", "content": [
        {"type": "document", "source": {
            "type": "base64", "media_type": "application/pdf", "data": pdf}},
        {"type": "text", "text": "What are the three key findings?"},
    ]}],
)
print(next(b.text for b in resp.content if b.type == "text"))

uploaded = client.beta.files.upload(
    file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
)
for q in ["Termination clause?", "Payment schedule?", "Governing law?"]:
    resp = client.beta.messages.create(
        model="claude-opus-4-8", max_tokens=1024,
        betas=["files-api-2025-04-14"],          # required on upload AND here
        messages=[{"role": "user", "content": [
            {"type": "text", "text": q},
            {"type": "document",
             "source": {"type": "file", "file_id": uploaded.id}},
        ]}],
    )
    print(q, "->", next(b.text for b in resp.content if b.type == "text")[:60])

client.beta.files.delete(uploaded.id)            # files persist until deleted

IN = 5.0 / 1e6   # $ per input token, Opus 4.8

def image_tokens(w, h):
    return round(w * h / 750)          # Anthropic's rough estimate

def image_cost(w, h):
    return image_tokens(w, h) * IN

print(image_tokens(1568, 1568), f"${image_cost(1568,1568):.5f}")  # ~3279  $0.01640
print(image_tokens(784, 784),   f"${image_cost(784, 784):.5f}")   # ~820   $0.00410
print(f"downsizing saves {100*(1-image_cost(784,784)/image_cost(1568,1568)):.0f}%")  # 75%

resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024,
    messages=[{"role": "user", "content": [
        {"type": "document",
         "source": {"type": "base64", "media_type": "application/pdf", "data": pdf},
         "title": "Q4 Report",
         "citations": {"enabled": True}},          # all-or-none across documents
        {"type": "text", "text": "What was Q4 revenue? Cite the source."},
    ]}],
)
for block in resp.content:
    if block.type == "text":
        print(block.text)
        for c in (block.citations or []):
            # PDF -> page_location; plain text -> char_location
            print("  cite:", c.cited_text, "p", getattr(c, "start_page_number", None))

def ingest_decision(size_mb, pages, reuse_count):
    if size_mb > 32:
        return "REJECT — exceeds 32 MB request limit; split the document"
    if pages > 600:
        return "REJECT — exceeds 600-page limit; chunk by section"
    if reuse_count >= 2:
        return "Files API — upload once, reference by file_id (avoid re-upload)"
    return "inline base64 — one-off use, simplest path"

print(ingest_decision(2, 40, 1))     # inline base64
print(ingest_decision(2, 40, 5))     # Files API (reused 5x)
print(ingest_decision(50, 40, 1))    # REJECT — too big

Knowledge check check yourself