Image support

A user uploads a photo of a receipt. You want Claude to extract the line items. Another user uploads a satellite image of a property. An insurance system wants a fire risk score. A third user uploads a screenshot of a diagram. A support agent wants a text description. All three are the same feature under the hood: send Claude an image alongside a text instruction and get a structured answer back. This lesson covers how to do that end to end, including the prompt engineering techniques that make vision actually work.

The image handling contract

A few limits to know up front:

• Up to 100 images per request, summed across all messages.
• Max 5MB per image.
• Single-image max dimensions: 8000 × 8000 pixels.
• Multi-image max dimensions: 2000 × 2000 pixels each.
• Source options: inline base64 encoding, or a URL Claude can fetch.
• Token cost: roughly (width_px × height_px) / 750 per image. Huge images are expensive — resize before sending if you don't need the full resolution.

The token cost is worth internalising. A 4000 × 3000 image costs about 16,000 tokens just for the image, before the prompt or the response. If you're building high-volume pipelines, resize images down to the smallest dimensions at which your task still works. Vision tasks that can use thumbnails should use thumbnails.

Sending an image

An image goes into a user message as a block, alongside text blocks. The content list is heterogeneous — same shape you've been working with for tool use, just with image blocks instead of tool_use blocks.

import base64

with open("image.png", "rb") as f:
    image_bytes = base64.standard_b64encode(f.read()).decode("utf-8")

add_user_message(messages, [
    {
        "type": "image",
        "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": image_bytes,
        },
    },
    {
        "type": "text",
        "text": "What do you see in this image?",
    },
])

Three things going on:

• type: "image" identifies the block as an image.
• source carries the encoding type, the media type (image/png, image/jpeg, image/gif, image/webp), and the base64-encoded bytes themselves.
• The text block comes after the image. You can put multiple image and text blocks in any order, but a common pattern is image-then-instruction.

For an image hosted at a URL, you can swap the source for a URL reference — Anthropic's docs have the exact shape, and the rest of the block stays the same.

From here, calling chat(messages) works exactly like a text-only conversation. Claude responds with a text block containing its analysis.

The simple prompt trap

The single biggest mistake with vision is treating it as magic — throwing an image at Claude with a one-line question and expecting reliable results. It doesn't work that way.

"How many marbles are in this image?" is a one-line prompt that will often produce a confident, wrong number. Vision tasks are hard; a small conceptual nudge from "ask the model a question" to "give the model a methodology" produces dramatically better results.

The rule that matters: every prompt engineering technique from Module 5 applies to vision. Clarity and directness, specificity with guidelines and process steps, XML structure, one-shot and multi-shot examples. If a simple text prompt is insufficient, the same prompt with an image attached is also insufficient. You have to engineer the visual prompt.

Step-by-step visual analysis

Instead of asking a question, give Claude a procedure:

Analyse this image of marbles and determine the exact count using
this methodology:

1. Begin by identifying each unique marble one at a time. Assign
   each a number as you identify it.
2. Verify your result by counting with a different method. Start
   from the bottom-left corner and work row by row, from left to
   right.

What is the exact, verified number of marbles in this image?

Now Claude has a procedure. Two independent counting passes, a final verification, and a clean numeric answer at the end. This is the process-steps technique from Module 5 applied to a visual task, and it works the same way it does for text — forcing the model to think through the problem rather than guess.

One-shot visual examples

If the task has a specific interpretation you want Claude to match, include an example image in the message:

1. First, an image with a known answer.
2. Then, the correct answer stated explicitly.
3. Then, the target image.
4. Finally, the question.

This gives Claude a reference point. "Here's how I counted the marbles in this image — the answer was 47. Now count this second image the same way." You're essentially showing Claude the grading rubric for the task in visual form.

A real-world example: fire risk assessment

Here's a production-shaped example: automating fire risk assessment for home insurance from satellite imagery. A field inspector would take an hour per property; Claude can process the same image in seconds if the prompt is engineered properly.

A naive prompt — "Provide a fire risk score for this property" — produces unreliable, inconsistent scores. A structured prompt with explicit methodology gets much closer to human-quality results:

Analyse the attached satellite image of a property with these
specific steps:

1. Residence identification: Locate the primary residence on the
   property by looking for:
   - The largest roofed structure
   - Typical residential features (driveway connection, regular geometry)
   - Distinction from other structures (garages, sheds, pools)

2. Tree overhang analysis: Examine all trees near the primary residence:
   - Identify any trees whose canopy extends directly over any portion
     of the roof
   - Estimate the percentage of roof covered by overhanging branches
     (0-25%, 25-50%, 50-75%, 75%+)
   - Note particularly dense areas of overhang

3. Fire risk assessment: For any overhanging trees, evaluate:
   - Potential wildfire vulnerability (ember catch points, continuous
     fuel paths to structure)
   - Proximity to chimneys, vents, or other roof openings
   - Areas where branches create a "bridge" between wildland vegetation
     and the structure

4. Defensible space identification: Assess the property's overall
   vegetative structure:
   - Identify if trees connect to form a continuous canopy over or
     near the home
   - Note any obvious fuel ladders

5. Fire risk rating: Based on your analysis, assign a Fire Risk Rating
   from 1-4:
   - Rating 1 (Low Risk): No tree branches overhanging the roof,
     good defensible space around the home
   - Rating 2 (Moderate Risk): Minimal overhang (<25% of roof), some
     separation between tree canopies
   - Rating 3 (High Risk): Significant overhang (25-50% of roof),
     connected tree canopies, multiple vulnerability points
   - Rating 4 (Severe Risk): Extensive overhang (>50% of roof),
     dense vegetation against structure

For each item above (1-5), write one sentence summarising your
findings, with your final response being the numerical rating.

Look at what this prompt is doing:

• Explicit process steps — Claude is told exactly what to examine and in what order.
• Detailed output guidelines — the rating scale is defined, not assumed.
• Structured final output — one sentence per step plus a final numeric rating, which is trivial to parse downstream.
• Domain vocabulary — "fuel ladders," "defensible space," "ember catch points" — the technical terms that anchor the analysis in real fire-risk methodology.

That prompt is the difference between a demo and a production system. Well-crafted visual prompts produce repeatable, structured, trustworthy analyses. Casual prompts produce whatever Claude feels like that turn.

Takeaway: same rules, new modality

Images are a new input modality but the prompt engineering playbook is unchanged. Spend as much effort on the prompt for a visual task as you would on the prompt for the equivalent text task. Validate with evals — the same PromptEvaluator pattern from Module 5 works on visual tasks with image-containing datasets — and iterate until the score is where it needs to be. Nothing about adding images changes the economics of prompt engineering.