Long Documents, Multimodal Input, and a First Look at the API: Using Large Context, Saving Money With Prompt Caching, PDF and Image Input, Citation-Backed Answers; a Minimal Messages API Call

Today's Goals

1. Make one Messages API call with the official SDK, and read the content blocks and usage in the response
2. Pass a PDF or image to Claude as a content block, and turn on citations to get page-numbered references
3. Explain where prompt caching saves money, when it doesn't, and verify a cache hit from the usage field

Yesterday was about how to brief the teammate. Today we start handing over material — a whole document of several dozen pages of it. Once you have read this and finished the lab, scroll back up and tick off the three goals.

Plain-Language Walkthrough

The minimal Messages API call: what is in one request

Yesterday's code quietly used the API once already; today we open it up. Every exchange with the teammate is, at the API level, one HTTP request to the Messages API. A request carries four things at minimum: which model (model), how much it may say at most (max_tokens), the business card (system, optional), and the conversation so far (messages). What comes back is not a piece of text either, but an array of content blocks (content), each with its own type: text is text, a tool the model wants to call is tool_use, and with thinking enabled there will also be thinking blocks. The sentence you actually wanted is the block whose type is text.

Hanging off the end of the response is a usage object recording how many input tokens went in and how many output tokens came out. This is today's most important field, because every technique we cover today ultimately relies on it to prove whether anything was actually saved. Write the minimal call first and print usage to see it:

import Anthropic from '@anthropic-ai/sdk'
 
const client = new Anthropic() // reads ANTHROPIC_API_KEY
 
const res = await client.messages.create({
  model: 'claude-sonnet-5',
  max_tokens: 512,
  system: 'You are a patient technical writer. Answer in three sentences or fewer.',
  messages: [{ role: 'user', content: 'Explain what a context window is in one sentence.' }],
})
 
// content is an array of blocks, not a string
const text = res.content
  .filter((b) => b.type === 'text')
  .map((b) => b.text)
  .join('')
console.log(text)
 
// usage is today's lead role: every technique gets verified through it
console.log(`input=${res.usage.input_tokens} output=${res.usage.output_tokens}`)
console.log(`stop_reason=${res.stop_reason}`) // end_turn / max_tokens / tool_use …

import anthropic
 
client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
 
res = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=512,
    system="You are a patient technical writer. Answer in three sentences or fewer.",
    messages=[{"role": "user", "content": "Explain what a context window is in one sentence."}],
)
 
# content is a list of blocks, not a string
text = "".join(b.text for b in res.content if b.type == "text")
print(text)
 
# usage is today's lead role: every technique gets verified through it
print(f"input={res.usage.input_tokens} output={res.usage.output_tokens}")
print(f"stop_reason={res.stop_reason}")  # end_turn / max_tokens / tool_use …

Memorize two details right now. First, stop_reason tells you why the model stopped: end_turn means it finished, and max_tokens means your ceiling cut it off — treating a summary that was chopped in half as a complete result is the most common silent error beginners hit. Second, do not set max_tokens stingily; it is a hard ceiling, not a target length. The model will not be more concise because you gave it 512, it will just be truncated.

Large context is not free context: the bigger the window, the more you should count what each request hauls

The context window of Claude's current flagship models is on the order of a million tokens, so a PDF of several dozen pages or tens of thousands of lines of code fits whole. The first reaction is usually "then length no longer matters" — and that is the first intuition today has to correct.

Back to the teammate analogy: you hand them a box of material, and every time they answer a question they have to read the whole box again from the top. The model is stateless; every request starts from zero and reads everything you sent, and input tokens are billed per request. A 60-page PDF runs roughly 1,500 to 3,000 tokens per page, so about 100,000 tokens for the whole thing; ask ten questions around it and that is a million input tokens. Even at a low unit price that is real money, never mind waiting for it to read 100,000 tokens before it starts answering each time.

A large window solves "it fits." It does not solve "it gets re-read every time." So the core skill of the large-context era is not how to cram more in, but counting what each request hauls and which part of it is hauled repeatedly. The two remaining techniques today — citations and prompt caching — make the hauling auditable and make the repeated part cost a fraction.

PDF and image as content blocks: the model sees more than the text

The previous section said "stuff the PDF in." How, exactly? Not by converting the PDF to plain text with a tool and pasting that into the prompt — that scatters tables and drops figures. The Messages API lets you place a document block directly in the content of a message, with source holding the PDF as base64; images work the same way with an image block. For each page of a PDF, Claude both reads the text and looks at the layout, so it can make sense of charts, tables, and handwritten annotations.

A few hard limits to remember: 32 MB per request, at most 600 pages (100 pages on models whose context window is under a million tokens), and no encrypted PDFs. A very dense PDF — small type, complex tables, lots of images — may fill the window before it hits the page limit, in which case split it by chapter. One more piece of advice follows yesterday's "material first, instructions last": put the document block before the text block, so the model sees the material before the question.

Since you will ask about the same PDF repeatedly, resending the base64 every time also wastes bandwidth. There is a separate Files API you can upload to once and then reference by file_id, sending only the id in later requests. Today's lab uses base64 to keep one concept off your plate; either is fine in production.

Citation-backed answers: citations make every sentence point back to a page

The teammate reads 60 pages and hands you a summary. Your first question is: which page said that? If they are paraphrasing from memory, you have to go back and verify everything yourself; if they tagged a page number after each sentence, you only have to spot-check.

There used to be exactly one way to do "with citations": ask the model in the prompt to quote the source and note the page, then hope it copies honestly. The problem is that a model paraphrases while it copies, and it can misremember the page — leaving you unable to distinguish "it really did cite" from "it believes it cited." Claude's citations feature moves this from a prompt convention to an API feature: add citations: { enabled: true } to the document block, and the returned text gets split into several blocks, each carrying a citations array holding the quoted source (cited_text), which document it came from (document_index), and the location — for a PDF that is page_location, with start_page_number and end_page_number (pages are 1-based and the end page is exclusive).

These citations are parsed and checked server-side by the API, so they always point at a passage that genuinely exists in the document; and cited_text does not count toward output tokens, making it cheaper than having the model copy the source itself. Wired into code:

import fs from 'node:fs'
import Anthropic from '@anthropic-ai/sdk'
 
const client = new Anthropic()
const pdf = fs.readFileSync('report.pdf').toString('base64') // base64 must not contain newlines
 
const res = await client.messages.create({
  model: 'claude-sonnet-5',
  max_tokens: 2048,
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'document', // material first
          source: { type: 'base64', media_type: 'application/pdf', data: pdf },
          title: 'report.pdf',
          citations: { enabled: true }, // turn citations on
        },
        {
          type: 'text',
          text: 'Summarize the core conclusions of this report in five sentences, each backed by evidence.',
        }, // instructions last
      ],
    },
  ],
})
 
// With citations on, the text arrives as several text blocks, each possibly carrying citations
for (const block of res.content) {
  if (block.type !== 'text') continue
  const pages = (block.citations ?? [])
    .filter((c) => c.type === 'page_location')
    .map((c) => `p.${c.start_page_number}`) // end_page_number is exclusive; for one page just read start
  process.stdout.write(block.text + (pages.length ? ` [${pages.join(', ')}]` : ''))
}

import base64
import anthropic
 
client = anthropic.Anthropic()
pdf = base64.standard_b64encode(open("report.pdf", "rb").read()).decode()  # no newlines
 
res = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",  # material first
                    "source": {"type": "base64", "media_type": "application/pdf", "data": pdf},
                    "title": "report.pdf",
                    "citations": {"enabled": True},  # turn citations on
                },
                {
                    "type": "text",
                    "text": "Summarize the core conclusions of this report in five sentences, each backed by evidence.",
                },  # instructions last
            ],
        }
    ],
)
 
# With citations on, the text arrives as several text blocks, each possibly carrying citations
for block in res.content:
    if block.type != "text":
        continue
    pages = [
        f"p.{c.start_page_number}"  # end_page_number is exclusive; for one page just read start
        for c in (block.citations or [])
        if c.type == "page_location"
    ]
    print(block.text + (f" [{', '.join(pages)}]" if pages else ""), end="")

One limit came up yesterday: citations and structured output cannot be enabled together. So "a summary with page numbers" and "fill in a JSON form" are two different paths — when you need citations, use the feature and assemble the text blocks yourself; when you need a strict structure, give up API-level citations and leave a page field in the schema for the model to fill in itself (which is a notch less reliable).

Prompt caching: store the unchanging prefix and pay a fraction for repeat questions

Back to the problem of re-reading the whole box every time. If the teammate builds an index on the first pass, the second and third questions no longer need a read from the top. Prompt caching is that index: you mark a spot in the request saying "cache everything up to here," the server stores the processed state of that prefix, and for the next few minutes any request with a byte-identical prefix reuses it and pays a fraction.

The key word is prefix. Cache matching covers every byte from the start of the request up to the cache_control marker, in the order tool definitions, then system, then messages. Change one byte and every cache after it is invalidated. That explains yesterday's "do not put a date on the business card": put a timestamp that changes every time at the top of the system prompt and the prefix will never line up, so the cache never hits once. The right layout is unchanging content first (system, documents), changing content after (this turn's question), with the cache marker at the end of the unchanging part.

On price, the request that writes the cache costs 1.25 times the normal input price, and each later hit costs 0.1 times. So it is not free: ask a single question about one document with caching on and you pay 25% more; you only start netting a saving from the third question on. The cache lives 5 minutes by default and each hit refreshes it; there is also a 1-hour tier at 2 times the write price, suited to longer gaps. There is also a minimum length threshold (1,024 tokens on current flagship models, 4,096 on Haiku 4.5), and a prefix below it is neither cached nor flagged as an error — one of the most common reasons for "caching is on but nothing hits."

Put the cache marker on the document block:

import fs from 'node:fs'
import Anthropic from '@anthropic-ai/sdk'
 
const client = new Anthropic()
const pdf = fs.readFileSync('report.pdf').toString('base64')
 
async function ask(question: string) {
  const res = await client.messages.create({
    model: 'claude-sonnet-5',
    max_tokens: 1024,
    messages: [
      {
        role: 'user',
        content: [
          {
            type: 'document',
            source: { type: 'base64', media_type: 'application/pdf', data: pdf },
            cache_control: { type: 'ephemeral' }, // cache up to here: the doc is fixed, the question varies after it
          },
          { type: 'text', text: question },
        ],
      },
    ],
  })
  const u = res.usage
  // First call: cache_creation is large, cache_read is 0. From the second on: cache_read is large, cache_creation is 0
  console.log(
    `write=${u.cache_creation_input_tokens} read=${u.cache_read_input_tokens} uncached=${u.input_tokens}`
  )
}
 
await ask('What are the core conclusions of this report?')
await ask('Which risks does the report mention?') // same prefix, cache hit

import base64
import anthropic
 
client = anthropic.Anthropic()
pdf = base64.standard_b64encode(open("report.pdf", "rb").read()).decode()
 
 
def ask(question: str) -> None:
    res = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "document",
                        "source": {"type": "base64", "media_type": "application/pdf", "data": pdf},
                        # cache up to here: the doc is fixed, the question varies after it
                        "cache_control": {"type": "ephemeral"},
                    },
                    {"type": "text", "text": question},
                ],
            }
        ],
    )
    u = res.usage
    # First call: cache_creation is large, cache_read is 0. From the second on: the reverse
    print(f"write={u.cache_creation_input_tokens} read={u.cache_read_input_tokens} uncached={u.input_tokens}")
 
 
ask("What are the core conclusions of this report?")
ask("Which risks does the report mention?")  # same prefix, cache hit

Verifying with usage: did the cache actually hit

We have covered what ought to save money. How do you know it did? The answer goes back to usage from the first section. With caching on it gains two fields: cache_creation_input_tokens is how many tokens this request wrote into the cache, and cache_read_input_tokens is how many it read out of the cache; the original input_tokens now means the part not covered by any cache. Only the sum of all three is the input this request truly processed.

A healthy write-then-read looks like this: on the first request cache_creation is roughly the size of the document and cache_read is 0; on the second, cache_read is roughly the size of the document, cache_creation is 0, and input_tokens is down to the few dozen tokens of the question. If cache_read is still 0 on the second call, work through the list: is there anything in the prefix that varies (a timestamp, a random id, unsorted JSON); are both requests using the same model; did the prefix clear the minimum length threshold; was the gap longer than 5 minutes; is the tool list in the same order. Those five cover nine out of ten cache misses.

Baking that check into your code is a good habit: log all three fields, build a cache hit rate metric, and one glance after a deploy tells you whether someone broke the prefix design. That is the last step of today's lab, and it is also the first self-check to run whenever you pick up any long-document requirement in the future.

Source Reading

Hands-On Lab

Confirm two things before you start: that you have an unencrypted PDF of a few to a few dozen pages (use the bundled sample.pdf in the lab directory if not), and that your key is in ANTHROPIC_API_KEY in .env — with no key, run everything under MOCK=1. If you get stuck, read the common pitfalls section of the README first.

1. Run pnpm install in the starter directory, then MOCK=1 pnpm start sample.pdf. Seeing a mock summary with [p.N] markers confirms the skeleton runs.
2. Finish exercise 1: read the PDF as base64 into a document block, enable citations, and place the document block before the text block.
3. Finish exercise 2: walk the returned content blocks, append the start page of each page_location to the matching sentence, and print stop_reason at the end.
4. Finish exercise 3: add cache_control to the document block, ask two questions in a row, and print and compare the three cache-related usage fields.
5. Swap the summary question for three different questions and run again, watching whether cache_read hits consistently. If it does not, work through the five-item list from the walkthrough.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward why the context window is the scarcest resource, the prefix semantics of prompt caching, and how citations differ from asking the model to copy the source itself. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• Make one Messages API call with the official SDK, and read the content blocks and usage in the response
• Pass a PDF or image to Claude as a content block, and turn on citations to get page-numbered references
• Explain where prompt caching saves money, when it doesn't, and verify a cache hit from the usage field
• Recite the five-item checklist for a cache that will not hit
• All 5 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D3) we leave the API and enter Claude Code — a teammate that reads files, runs commands, and edits code on its own. You will install it, write the first CLAUDE.md for your own project, walk through explore-then-plan-then-implement with Plan Mode, and for the first time actually hand the example task of adding validation and tests to the TODO API over to it. Today's "context is the scarcest resource" becomes a daily reality there: every file Claude Code reads and every command it runs spends the same window, which is why half of D3 is about managing it.