How do you combine several images with text in one Claude Messages API turn?

## Several blocks, one array The `content` array of a user message is an ordered sequence, and nothing restricts it to one image. A comparison turn typically looks like: text block naming the first image, image block, text block naming the second image, image block, then a final text block with the actual question. That structure is not required by the schema — a bare run of image blocks followed by one question works — but it is what makes multi-image answers reliable. ## Why labelling matters Without labels, the model has to refer to the images positionally, and so do you. Answers drift into "the first picture" and "the other one", which is fine for a human reading the transcript and terrible for a program parsing it. Naming the images in adjacent text blocks gives both sides a shared vocabulary: you can ask "which elements changed between Screenshot A and Screenshot B" and get an answer that uses those names. This is the documented recommendation and it costs a handful of tokens. The related recommendation is to put images before the text that asks about them. The model reads the array in order, so presenting the evidence before the question mirrors how a person would be briefed. ## Cost is additive, and it repeats Each image is tokenised on its own and the counts sum into `usage.input_tokens`. There is no discount for volume and no deduplication of identical images. At the high-resolution tier a single image can approach roughly 4784 tokens, so a handful of full-resolution screenshots is already a substantial prompt before any text. Because the Messages API is stateless, every image in the history is re-sent — and re-billed — on each subsequent request in that conversation. A multi-image turn early in a long agent loop is therefore not a one-time cost. Once the model has extracted what it needs, replacing those image blocks with a short text summary of the findings is one of the largest savings available in a vision-heavy agent, and it usually improves focus as well. ## Choosing a batching strategy Put images in the same turn when the task genuinely requires seeing them together: before/after diffs, picking the best of several candidates, reading a document split across page images, tracking a UI flow across steps. Split them into separate requests when the images are independent — classifying a thousand product photos is a thousand requests (or a batch job), not one request with a thousand images, because separate requests parallelise, fail independently, retry cheaply, and never carry each other's tokens. A useful middle ground for very long document flows is chunking: send pages in groups, summarise each group into text, and carry only the summaries forward. That keeps any single request within a sane token budget while preserving continuity. ## Limits and legality Up to 100 images may appear in one request. Image blocks remain user-side only, including when they arrive nested inside a `tool_result` block — for example an agent tool that returns a screenshot. The assistant never produces image blocks, so a multi-image conversation is always you supplying pictures and Claude answering in text. ## Ordering pitfalls Two failure patterns recur. The first is asking the question first and appending the images afterwards, which weakens grounding for exactly the reason the guidance exists. The second is interleaving so heavily that the question is buried — a long alternation of images and commentary with the actual instruction lost in the middle. Keep the structure simple: label, image, label, image, then one clear instruction at the end.