Image Inputs: Formats, Size Limits, Base64 vs URL

Vision is a core Messages API capability, available on all four third-party platforms as well as the first-party API. You attach images as image content blocks inside a user message, alongside ordinary text blocks. This article covers what the API accepts, what it costs, and the platform differences that trip teams up.

Formats and hard limits

Claude accepts four image formats: JPEG, PNG, GIF, and WebP (image/jpeg, image/png, image/gif, image/webp). Animated GIFs and animated WebP are not interpreted as animations — only the first frame is used.

Per-request counts: up to 100 images for models with a 200K context window, and up to 600 for the 1M-context models. There is a catch above 20 images: requests with more than 20 image or document blocks apply a stricter per-image limit of 2000 pixels per dimension, and violations return an invalid_request_error mentioning "many-image requests". The whole request payload is also capped at 32 MB, which you can hit well before the image-count ceiling.

Base64, URL, or file reference?

Base64 — you encode the bytes into the request. It works everywhere, including Amazon Bedrock and Google Cloud, which currently support base64 only. The downside is payload bloat: base64 inflates file size, and every retry re-sends the bytes.

URL — you pass a publicly reachable URL and the API fetches it. Requests stay small, but the image must be accessible from the internet, which rules out anything behind your firewall. Not available on Bedrock or Google Cloud.

Files API reference — upload once, then reference a file_id in as many requests as you like. This is the right pattern when the same image appears in many requests, and it keeps you under the 32 MB payload limit. The Files API is a beta feature available on the Claude API, Claude Platform on AWS, and Microsoft Foundry — not on Bedrock or Google Cloud (see the Files API article).

from anthropic import AnthropicBedrockMantle
import base64

client = AnthropicBedrockMantle(aws_region="us-east-1")
img = base64.standard_b64encode(open("invoice.png", "rb").read()).decode()
msg = client.messages.create(
    model="anthropic.claude-sonnet-5", max_tokens=1024,
    messages=[{"role": "user", "content": [
        {"type": "image", "source": {"type": "base64",
         "media_type": "image/png", "data": img}},
        {"type": "text", "text": "Extract the invoice total and due date."},
    ]}],
)

Note the ordering: Claude works best when images come before the text that asks about them.

What images cost

Images are billed as input tokens. Claude processes them in 28×28-pixel patches, so the cost is ceil(width/28) × ceil(height/28) visual tokens — a 1000×1000 px image costs 1,296 tokens. Multiply by your model's input price to get dollars.

Resolution tier matters. Claude Fable 5, Opus 4.8, Opus 4.7, and Sonnet 5 are high-resolution models: images are downscaled only when the long edge exceeds 2576 px, up to a maximum of 4,784 visual tokens per image. All other models downscale to a 1568 px long edge and cap at 1,568 tokens. The same photo can therefore cost up to roughly three times more visual tokens on a high-resolution model. If you don't need the fidelity — say, for coarse classification — downsample images yourself before sending.

Practical constraints to plan around

Claude cannot identify or name people in images, cannot generate or edit images, and does not read embedded image metadata (EXIF and the like) — strip nothing, expect nothing. Image uploads are ephemeral: they are not stored beyond the request. If your compliance team asks where the image "lives", the answer is: in the request, and — on 3P — inside your cloud provider's boundary, inheriting that provider's posture; confirm specifics with your provider.

Where to go next

PDFs behave like images plus extracted text — see PDF support. For repeated images across requests, read the Files API, and check the feature matrix for platform-by-platform coverage.

Sources

• Vision — Claude Docs
• Files API — Claude Docs
• Model migration guide — Claude Docs