Claude API Image Understanding: Vision Example Guide

Claude's vision capability lets you send images alongside text in a single API request and get back a text response that describes, analyzes, or extracts data from what it sees. This covers a working Claude API image understanding example — how to format the request, encode images, handle multiple images, and avoid the mistakes that cause silent failures.

The short answer: you send an image as a base64-encoded block (or a public URL) inside the same content array as your text prompt, in a standard messages request. No separate "vision endpoint" exists — image understanding is just another content type on the Messages API. Below are full examples you can copy and run.

How Claude's Vision Input Works

Claude models with vision support accept images as one of several content block types in a message. Each message's content field is an array, and you mix type: "text" and type: "image" blocks freely within the same user turn. Claude processes the image(s) and text together as one prompt — it doesn't caption the image first and then reason over the caption, so you get much richer understanding (layout, relationships between objects, reading text in screenshots, comparing two images side by side).

Supported image formats are JPEG, PNG, GIF (first frame only), and WebP. There's a practical limit on image size and resolution — very large images are automatically downscaled, so sending a 20MB photo doesn't give you better accuracy than sending a reasonably compressed version.

Basic Example: Describing an Image (base64)

The most common pattern is base64-encoding a local image file and embedding it directly in the request.

IMG_BASE64=$(base64 -i screenshot.png | tr -d '\n')

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/png",
              "data": "'"$IMG_BASE64"'"
            }
          },
          {
            "type": "text",
            "text": "What error is shown in this screenshot, and which line of code is it pointing to?"
          }
        ]
      }
    ]
  }'

Claude will return a text response identifying the error message and relevant code line, treating the screenshot as structured visual data rather than a blob to OCR separately.

Using an Image URL Instead of base64

If your image is already hosted (e.g., a product photo on S3 or a CDN), you can reference it by URL instead of encoding it:

{
  "type": "image",
  "source": {
    "type": "url",
    "url": "https://example.com/images/invoice-scan.jpg"
  }
}

This is faster to implement for pipelines that already store images remotely, since you skip the base64 encoding step entirely.

JavaScript Example: Multi-Image Comparison

A common real-world use case is comparing two images — before/after screenshots, two product photos, or a diagram against a reference. Here's a JavaScript example sending two images in one request:

import fs from "fs";

const img1 = fs.readFileSync("before.png").toString("base64");
const img2 = fs.readFileSync("after.png").toString("base64");

const response = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ANTHROPIC_API_KEY,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-opus-4-20250514",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [
          { type: "image", source: { type: "base64", media_type: "image/png", data: img1 } },
          { type: "image", source: { type: "base64", media_type: "image/png", data: img2 } },
          { type: "text", text: "Describe exactly what changed between these two UI states." }
        ],
      },
    ],
  }),
});

const data = await response.json();
console.log(data.content[0].text);

Claude understands ordering — telling it "the first image" and "the second image" in your prompt text reliably maps to the order the image blocks appear in the array.

Practical Use Cases for Vision

Image understanding is most useful in production for:

• Document and invoice extraction — pulling structured fields (totals, dates, line items) from scanned PDFs rendered as images or photos
• UI/QA automation — comparing rendered screenshots against a spec or flagging visual regressions
• Chart and diagram reading — summarizing a chart's trend or explaining what a flowchart depicts
• Content moderation — classifying uploaded images against policy descriptions in natural language
• Accessibility tooling — generating alt text or descriptions for images in a CMS pipeline

For all of these, keep your text prompt specific. "Describe this image" gives you a generic caption; "List every line item and its price from this invoice, as JSON" gives you a usable, parseable output.

Routing Vision Requests Through SubToAPI

If you're building vision features into a product and need your team to call Claude without juggling raw Anthropic credentials, SubToAPI exposes the same Messages API — including image content blocks — behind an application key (sub_live_...). You get per-key usage metadata (so you can see which feature or customer is driving image-processing costs), streaming support, and team seats, all from one dashboard. The request body and content types shown above work unchanged — see the Messages API docs for the full reference, or the quickstart to get an API key in a couple of minutes. Pricing starts at €9/month on the Solo plan, with Team and Scale plans for multi-seat setups — check /pricing for details, and /signup to start a free trial.

Common Mistakes to Avoid

• Sending oversized images without compression — resize to a reasonable max dimension (around 1568px on the long edge is a sensible ceiling) before encoding
• Forgetting the media_type must exactly match the actual file format, not just the file extension
• Mixing up block order and referring to "the second image" when only one was sent
• Expecting pixel-perfect OCR on extremely low-resolution or heavily compressed screenshots — quality in, quality out

Questions

Does Claude have a separate vision API endpoint? No. Image understanding uses the same Messages endpoint as text — you add an image content block alongside your text block in the same request.

What image formats and sizes does Claude support? JPEG, PNG, WebP, and GIF (first frame only). Very large images are automatically downscaled, so compressing before upload is a good practice for speed and cost.

Can I send multiple images in one Claude API request? Yes. Add multiple image content blocks in the content array of a single message; Claude processes them together and respects the order you send them in.