Anthropic vision and PDF input: base64 image and document blocks with media_type, check size limits

TL;DR

The Messages API reference covers image/jpeg among the supported media types; always set the media type to match the actual bytes. Keep the image or document block in the user message content array alongside text blocks.

Steps

1. Images are sent as image content blocks with a base64 source and an explicit media type. The Messages API reference covers image/jpeg among the supported media types; always set the media type to match the actual bytes.
2. PDFs are sent as document content blocks. The API reference covers application/pdf. Like images, they travel inside the message content array, not as attachments or links.
3. Base64-encode on the server just before the request. Do not store or forward larger-than-needed encodings; base64 inflates size by a third, which matters against request size limits.
4. Keep the image or document block in the user message content array alongside text blocks. Order matters for the model's reading: put the visual content where the text refers to it.
5. Watch request size limits on multimodal calls. Oversized payloads are rejected, so downscale or compress images before encoding rather than after a failure.
6. If you cache prompts containing documents, the document blocks are the stable prefix candidates; mark the breakpoint after them so repeated questions over the same document hit the cache.
7. Failure modes this prevents: wrong or missing media type strings; oversized requests from uncompressed images; document blocks placed where the cache cannot reuse them.

When to use

You are seeing this: Images are sent as image content blocks with a base64 source and an explicit media type. Use this skill when you run into "Anthropic vision and PDF input: base64 image and document blocks with media_type, check size limits".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

The Messages API reference covers image content blocks with image/jpeg media types and document blocks with application/pdf. Verified live at https://docs.anthropic.com/en/api/messages.