Vision, Documents, the Files API and Citations¶

Level: Intermediate · Time: ~60 min · Exam relevance: CCAO-F D2 · CCAR-P D2, D3

In plain English¶

Claude can read more than typed text. In the API you can send:

Images (photos, screenshots, charts, scanned forms) as image content blocks.
PDFs and text documents as document content blocks. Claude reads both the text and, for PDFs, the visual layout: tables, charts and images on the page.

Two features make working with files practical:

The Files API lets you upload a file once and refer to it by ID in many requests, instead of re-sending the bytes every time.
Citations make Claude point to the exact passages in your documents that support each part of its answer, in a machine-readable form you can verify and display.

Why it matters¶

Much enterprise knowledge lives in PDFs, scans and screenshots. Native support avoids fragile pre-processing.
Citations turn "trust me" answers into checkable ones, which matters for regulated work, audits and user trust. Evaluating outputs for accuracy and applying fact-checking techniques are Foundations objectives (CCAO-F-2.1, 2.3).
Architects must understand the size, cost and platform constraints of multimodal input (CCAR-P-2.4) and the grounding options for retrieval systems (see Module 11).

How it works¶

Images¶

An image block has a source of one of three types: base64 (bytes in the request), url (an image hosted online) or file (a Files API ID). On Amazon Bedrock and Google Cloud, only base64 is available (as of 2026-10-24).

Key facts from the vision documentation, checked 2026-10-24:

Topic	Detail
Formats	JPEG, PNG, GIF (first frame only), WebP
Images per request	Up to 600 on the API (100 for models with a 200k-token context window); 20 per message in claude.ai
Size per image	10 MB base64 on the Claude API; 5 MB on Amazon Bedrock
Dimensions	Up to 8000 x 8000 px; a stricter limit applies when a request has more than 20 images (resize to 2000 px or less on the long edge to be safe)
Token cost	Images are processed in 28 x 28 px patches: roughly `ceil(width/28) x ceil(height/28)` tokens, after any downscaling
Resolution	Claude 4.7 and later models accept up to 2,576 px on the long edge (about 4,784 visual tokens); larger images are downscaled

Practical guidance:

Put images before the question, just as you put long documents first.
Label multiple images ("Image 1:", "Image 2:") so you can refer to them.
Downsample when you do not need fine detail; high-resolution images can cost several thousand tokens each.
Know the limits: Claude will not identify people by name in images; counts of many small objects, precise spatial positions and very small or rotated images are less reliable; it cannot tell whether an image is AI generated; and it is not a diagnostic tool for medical scans.

PDFs and documents¶

A document block accepts PDFs (base64, URL or Files API) and plain text. As of 2026-10-24, a request can be up to 32 MB and a PDF up to 600 pages (100 pages for models with a 200k-token context window). Each PDF page is processed as both extracted text and an image of the page, so token use per page is higher than for plain text, and charts and tables are understood visually.

Tips:

Put the document block before your question text in the same user message.
Give each document a title so citations and answers can refer to it.
For repeated questions about the same document, add cache_control to the document block (see prompt caching).
For very large collections, retrieve relevant parts first (see RAG versus long context).

The Files API¶

Upload once, reference many times:

Fact (as of 2026-10-24)	Detail
Status	Generally available; use `client.files` (no beta header) on current SDKs
Max file size	500 MB
Storage	100 GB per organisation; files persist until you delete them
Cost	Upload, list and delete are free; file content used in a message is billed as input tokens
Scope	Files belong to the workspace of the API key that uploaded them
Availability	Claude API and Claude Platform on AWS; not Amazon Bedrock or Vertex AI; Microsoft Foundry only on Anthropic-hosted deployments (beta)

The content block type must match the file: document for PDFs and text, image for images. Files generated by tools such as code execution or Skills are also returned as file IDs you can download.

Citations¶

Enable citations per document with "citations": {"enabled": True}. You must enable it on all documents in a request or none. The response then contains several text blocks; blocks that make a claim carry a citations list:

Document type	Citation location fields
Plain text	`char_location`: `start_char_index`, `end_char_index`
PDF	`page_location`: `start_page_number`, `end_page_number` (1-indexed)
Custom content (pre-chunked)	`content_block_location`: block indexes

Every citation includes cited_text, document_index and document_title. The cited text does not count toward output tokens. Compared with asking for quotes in the prompt (quote-first grounding), API citations are guaranteed to point to real spans of your documents.

Citations cannot be combined with structured outputs in the same request (a 400 error, as of 2026-10-24). If you need both, make two calls or capture quotes as schema fields.

For your own retrieval systems, search_result content blocks let you pass retrieved passages with a source and title and receive citations to them in the same way.

Example¶

Northwind Lending (fictional) answers internal questions about its lending policy manual, a 180-page PDF. The PDF is uploaded once with the Files API, cached across questions, and answered with citations that are shown as footnotes.

from pathlib import Path

import anthropic

client = anthropic.Anthropic()  # API key from ANTHROPIC_API_KEY

# 1. Upload once (store the ID; do not re-upload on every request).
uploaded = client.files.upload(file=Path("data/lending_policy_manual.pdf"))
print("file id:", uploaded.id)


# 2. Ask questions with citations.
def ask_manual(question: str) -> None:
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4000,
        messages=[{
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": uploaded.id},
                    "title": "Lending Policy Manual v7",
                    "citations": {"enabled": True},
                    "cache_control": {"type": "ephemeral"},   # reuse the processed PDF across questions
                },
                {"type": "text", "text": question + " Answer only from the manual; say if it does not cover this."},
            ],
        }],
    )
    if response.stop_reason != "end_turn":
        print("Incomplete:", response.stop_reason)
        return

    footnotes = []
    for block in response.content:
        if block.type != "text":
            continue
        marker = ""
        for c in block.citations or []:
            footnotes.append(f"[{len(footnotes) + 1}] {c.document_title}, "
                             f"pp. {c.start_page_number}-{c.end_page_number}: \"{c.cited_text.strip()[:120]}\"")
            marker += f"[{len(footnotes)}]"
        print(block.text + marker, end="")
    print("\n\nSources:\n" + "\n".join(footnotes))


ask_manual("What is the maximum loan-to-value ratio for buy-to-let applications?")

Sending an image with base64 (for example, a photo of a damaged parcel label for Acme Logistics):

import base64

image_b64 = base64.standard_b64encode(Path("data/label_photo.jpg").read_bytes()).decode("ascii")
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": [
        {"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": image_b64}},
        {"type": "text", "text": "Read the tracking number and destination postcode. "
                                 "If either is unreadable, say 'unreadable' for that field."},
    ]}],
)

The Files API upload over raw HTTP:

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@data/lending_policy_manual.pdf"

Cost: requires API credits (live mode). PDF pages cost more tokens than plain text because each page is also processed as an image.

Enterprise use case¶

Contoso Health (fictional) processes supplier certificates (insurance, quality accreditation) that arrive as scanned PDFs. Previously staff typed key fields into the supplier system.

The new flow uploads each PDF with the Files API, extracts fields with structured outputs, and, in a second call with citations enabled, asks Claude to confirm each extracted value with its source page. A reviewer screen shows each field next to the cited snippet and page number, so staff verify rather than retype. Low-quality scans are flagged when Claude reports a field as unreadable, and those documents go to manual processing. Files are deleted from the Files API after 30 days in line with Contoso's retention schedule, because files otherwise persist until deleted.

Common mistakes¶

Re-sending large base64 files on every turn of a conversation. Use the Files API to keep requests small.
Question before the document or image. Put content first.
Ignoring image token costs. A batch of large screenshots can cost more than the text around it.
Enabling citations on some documents but not others. It must be all or none.
Combining citations with structured outputs. Rejected; split the calls.
Assuming files are deleted automatically. Uploaded files persist until you delete them.
Relying on vision for exact counts or coordinates without verification.

Security considerations¶

Documents and images can carry injected instructions, including text hidden in images or white-on-white text in PDFs. Treat their content as data and validate any action they suggest. See indirect prompt injection.
Personal data in scans. IDs, signatures and medical details often appear in documents; minimise, redact where possible, and follow retention rules. Delete Files API uploads when no longer needed.
URL sources. When you pass an image or document URL, make sure it points to content you are allowed to share; do not pass URLs supplied by untrusted users without validation.
Workspace scope. Files are visible to anyone with access to that workspace's API keys; separate sensitive workloads into their own workspaces.
Verification. Citations show where a claim came from; they do not prove the interpretation is right. Keep human review for high-stakes decisions.

Troubleshooting¶

Symptom	Likely cause	Fix
413 or request too large	Too many or too large inline files	Use the Files API; downsample images; split PDFs
400 about images in a many-image request	More than 20 images with large dimensions	Resize to 2000 px or less on the long edge, or send fewer images
400 when citations enabled	Combined with structured outputs, or enabled on only some documents	Separate calls; enable on all documents
404 on a `file_id`	File deleted, or uploaded in a different workspace	Check the workspace and the file list
Tables in a PDF misread	Low-resolution scan	Better scan quality; ask for "unreadable" when unsure
Unexpectedly high input tokens	Large images or many PDF pages	Downsample; extract relevant pages; cache the document

Check your understanding¶

What are the three image source types, and which one is available on every platform?
Why does a PDF page usually cost more tokens than the same text sent as plain text?
What does a PDF citation contain, and why is it stronger than prompted quoting?
Your application re-sends the same 40-page PDF on every turn of a chat. Name two improvements.

Answers

base64, url and file (Files API). Base64 is available everywhere; as of 2026-10-24, Amazon Bedrock and Google Cloud accept only base64.
Each page is processed both as extracted text and as an image of the page, so layout, tables and charts are understood visually.
cited_text, document_index, document_title, and start_page_number / end_page_number. The API guarantees the citation points to real text in your document, whereas prompted quotes can be paraphrased or invented.
Upload the PDF once with the Files API and reference it by ID; add cache_control to the document block so it is read from cache on later turns. (Retrieving only relevant pages is a third option.)