Multimodal Token Cost: The Image Patch Formula & the PDF document Block

The Image Token Formula

Claude does not see an image as one indivisible unit -- it views images in 28x28-pixel patches, and each patch is one visual token. That gives a concrete, computable cost:

visual_tokens = ceil(width / 28) * ceil(height / 28)

Worked example: a 1,000 x 1,000 pixel image is ceil(1000/28) x ceil(1000/28) = 36 x 36 = 1,296 visual tokens. Run the same formula on a few sizes to build intuition for how fast this scales:

At that rate, a handful of full-resolution screenshots in one request can consume as much context as a substantial system prompt -- ten of them can outweigh it. This is a budget line item to compute at design time, not something to discover once a pipeline is already in production against real-size inputs.

The Resolution Ceiling and Downscaling

Each model tier has its own maximum native image resolution, expressed as both a long-edge pixel limit and a visual-token ceiling, and these limits differ across model generations -- newer tiers generally accept larger images before hitting the ceiling. An image that exceeds either limit is downscaled before processing, and the token-cost formula then runs on the *scaled* dimensions, not the original ones. Practically: if you send an oversized image expecting the formula to apply to its native size, the actual token cost will be lower than a naive calculation predicts, because the image was shrunk first -- but you also lose whatever detail the downscale discarded. Confirm current per-tier limits against the vision documentation at build time, since they have changed between model generations before and will again.

PDFs Use a Different Block Type: document, Not image

A PDF is not sent as an image Content Block -- it uses a dedicated document block type. The source structure inside it follows the same pattern images use (it can be base64, a url, or a Files API file_id), but the surrounding block is document:

{
  "type": "document",
  "source": {
    "type": "base64",
    "media_type": "application/pdf",
    "data": "<base64-encoded-pdf-bytes>"
  },
  "title": "contract_review.pdf"
}

A few structural details about this block are easy to get wrong from memory:

• There is no required name field on a document block -- do not assume PDFs need a filename field the way some other systems require one.
• title (a readable document name) and context (additional metadata) are both optional -- neither is required to send a valid PDF request.
• Once loaded, a PDF's pages are subject to the same visual-token accounting as any other image content Claude reads from it -- the formula above and the per-tier resolution limits both still apply.

Base64 vs. Files API: The Reuse Question

Inline base64 encoding puts the full encoded payload directly in the message content -- simple, no upload step, but that means the entire payload travels on every single request. For a genuinely one-off image or document, that overhead is fine; the complexity of an upload flow wouldn't pay for itself. But for an asset that gets sent to Claude repeatedly across many requests -- a reference product diagram, a template document, a standing policy PDF -- base64 means paying the full transfer and (if the content counts toward tokens on each occurrence) the full token cost every single time. That is exactly the case the Files API and prompt caching exist to solve: upload or cache the asset once, reference it by file_id (or a cached prefix) on every subsequent call, and avoid re-transferring and re-tokenizing the same bytes over and over.

Common exam traps

• Applying the image-token formula to an oversized image's *original* dimensions instead of its downscaled dimensions -- the API downscales first, then tokenizes.
• Assuming a PDF needs a name field on its Content Block, or that title/context are required -- none of the three is mandatory.
• Sending a PDF as an image-type block instead of a document-type block.
• Reaching for inline base64 by default for an asset that's actually reused across many requests, paying the full transfer and token cost repeatedly instead of uploading once via the Files API.