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

Image and PDF input via content blocks

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.

Failure modes this prevents: wrong or missing media type strings; oversized requests from uncompressed images; document blocks placed where the cache cannot reuse them.

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.