Claude API Image Analysis: A Vision API Example

2026-10-23 · 4 min read · SubToAPI Team

Claude API Image Analysis: A Vision API Example

Claude's API accepts images directly inside the same messages endpoint you use for text — there's no separate "vision" endpoint. You send an image as a content block (base64-encoded or, depending on your setup, a URL) alongside a text prompt, and Claude returns a natural-language description, extraction, or analysis of what it sees.

This matters because it means image analysis isn't a bolted-on feature — it's a first-class input type. You can mix text and images in the same message, ask Claude to compare two screenshots, read a chart, transcribe handwritten notes, or flag issues in a UI mockup, all with the same request structure you already use for chat completions.

How Image Input Works

Claude's vision support is built around content blocks inside a message. Instead of (or in addition to) a text block, you add an image block with a source object specifying the media type and the base64 data:

{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/jpeg",
        "data": "<base64-encoded-image>"
      }
    },
    {
      "type": "text",
      "text": "What's shown in this image? List any text you can read."
    }
  ]
}

Supported formats are typically JPEG, PNG, GIF, and WebP. There are limits on image size and resolution per request, and on the number of images you can include in a single message — Claude will downscale large images internally, so sending something reasonably sized (under a few megabytes) is both faster and cheaper on tokens than sending a raw 20MB photo.

A Working curl Example

Here's a minimal example that reads a local image, base64-encodes it, and sends it to the Claude API for analysis:

IMAGE_BASE64=$(base64 -i screenshot.png)

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-sonnet-4-5",
    "max_tokens": 500,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/png",
              "data": "'"$IMAGE_BASE64"'"
            }
          },
          {
            "type": "text",
            "text": "Describe any errors visible in this screenshot and suggest a fix."
          }
        ]
      }
    ]
  }'

The response comes back in the same format as a text-only request — a content array with Claude's written analysis. There's no special "vision response" shape to parse.

A JavaScript Example

import fs from "fs";

const imageData = fs.readFileSync("chart.jpg").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-sonnet-4-5",
    max_tokens: 400,
    messages: [
      {
        role: "user",
        content: [
          {
            type: "image",
            source: { type: "base64", media_type: "image/jpeg", data: imageData }
          },
          { type: "text", text: "Extract the numbers from this chart as a JSON object." }
        ]
      }
    ]
  })
});

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

This pattern — base64 image plus a text instruction — covers the vast majority of real-world vision use cases.

Common Use Cases

UI/screenshot review: catching broken layouts, misaligned elements, or visible error messages
Document and form reading: extracting fields from scanned forms, invoices, or receipts
Chart and diagram interpretation: pulling structured data out of a graph image
Accessibility descriptions: generating alt text for images at scale
Content moderation triage: flagging images that need human review
Comparing before/after images: asking Claude to describe what changed between two screenshots in a single message

Things to Watch For

Image tokens count toward your usage. A large or high-resolution image consumes more tokens than a small one, so resizing images before sending them (especially for batch jobs) keeps costs predictable.

Multiple images per message are supported, but ordering matters — Claude processes them in the order they appear, so label each one in your accompanying text ("first image," "second image") if you need Claude to distinguish between them in its answer.

Streaming works the same way with vision inputs as with text — you'll get the analysis back as a stream of tokens rather than waiting for the full response, which is useful for longer descriptions or OCR-style extraction jobs.

If you're already running Claude through SubToAPI to get a stable sub_live_... API key, streaming, and usage metadata on top of your existing Claude access, the same /v1/messages endpoint accepts these image content blocks — see the messages docs for the exact request shape, or the quickstart if you're setting up a key for the first time.

Wrapping Up

Claude's vision capability is just another content block type on the same endpoint you already use, which makes it easy to add image analysis to an existing integration without rearchitecting anything. Start with a single base64 image and a clear text instruction, watch your token usage on larger images, and use multiple image blocks when you need comparisons. For teams running this in production with multiple services or seats, routing requests through SubToAPI adds a single dashboard for keys and spend across everyone using vision (and text) requests — check pricing for plan details.

questions

Do I need a separate API or model for image analysis with Claude? No. Vision-capable Claude models accept images as a content block type within the standard messages endpoint — there's no separate vision API or dedicated image model to call.

What image formats and sizes does Claude support? JPEG, PNG, GIF, and WebP are supported. Very large images are automatically downscaled, but sending images under a few megabytes keeps token usage and response times lower.

Can I send multiple images in one request for comparison? Yes. Include multiple image content blocks in a single message and reference them by order ("first image," "second image") in your text prompt so Claude knows which one you're asking about.

Claude API Image Analysis: A Vision API Example