Claude API Vision: Image Analysis Integration Guide

Claude's vision capability lets you send images alongside text in a single API request and get back structured analysis: descriptions, extracted text, classifications, chart readings, or answers to questions about what's in the picture. Integration is straightforward — you base64-encode the image (or reference a URL, depending on your setup) and include it as a content block in the same messages array you already use for text, no separate vision endpoint required.

If you're searching for how to wire this into a real product, the short answer is: Claude's multimodal messages API accepts image blocks and text blocks together, processes them in one inference pass, and returns a normal text response. There's no special "vision mode" to enable — you just build the right request payload. The rest of this guide covers the request format, supported image types, common use cases, and how to avoid the integration pitfalls that trip up most teams on their first vision feature.

How Claude's vision request format works

A multimodal message is a messages array where each message's content is a list of blocks. Mix image blocks and text blocks freely:

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": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "'"$(base64 -i receipt.jpg)"'"
          }
        },
        {
          "type": "text",
          "text": "Extract the total amount and date from this receipt."
        }
      ]
    }]
  }'

Key points worth knowing before you build around this:

• Supported formats: JPEG, PNG, GIF, and WebP.
• Multiple images per request: you can send several images in one message, which is useful for comparisons ("what changed between these two screenshots") or multi-page documents.
• Size limits: large images get resized internally, but you should still compress on your side — smaller images mean lower latency and lower token cost, since image tokens scale with resolution.
• No fine-tuning needed: vision works out of the box on current Claude models; you don't train or configure anything model-side.

If you're routing requests through SubToAPI instead of calling Anthropic directly, the same message structure applies — just point your request at https://api.subtoapi.app/v1/messages with your sub_live_... key and the identical content array works unchanged. That matters if you're already using SubToAPI for text-based features and want to add vision without restructuring your client code. See /docs/messages for the full request reference.

Common image analysis use cases

Teams building vision features tend to cluster around a handful of patterns:

1. Document and receipt extraction — pull structured fields (totals, dates, line items) from photos of invoices, receipts, or forms. Pair this with a JSON output instruction in your prompt so the response is directly parseable.
2. UI and screenshot QA — feed Claude a screenshot and ask it to flag layout bugs, missing elements, or accessibility issues. Useful in CI pipelines that capture visual regressions.
3. Content moderation and classification — categorize user-uploaded images (product photos, user avatars, listing images) against your own taxonomy by describing the categories in the prompt.
4. Chart and diagram interpretation — ask Claude to read values off a chart image or explain a technical diagram, which is far more reliable than trying to OCR-and-parse numbers yourself.
5. Accessibility alt-text generation — generate descriptive alt text for images at upload time, batching multiple images per request where layout allows.

For all of these, the pattern is the same: construct the image block, add a precise text instruction, and parse the text response. Combine this with tool use (see /docs/tools) if you want Claude to call a function with the extracted structured data instead of returning free text.

Building a production-ready vision pipeline

A few integration details separate a demo from something you can ship:

Pre-process on the client or server before sending. Resize images to a sensible max dimension (around 1568px on the longest side is a reasonable ceiling before you stop gaining accuracy) and re-encode as JPEG if the source is an uncompressed format. This cuts both latency and cost.

Validate media type and size before the request leaves your server. Reject unsupported formats early with a clear error rather than letting the API call fail downstream — it's a better user experience and saves you a wasted request.

Stream the response if you're generating long descriptions. Vision requests support the same streaming behavior as text-only requests, so a user uploading a complex diagram and asking for a full breakdown doesn't have to stare at a blank screen. See /docs/streaming for details on handling server-sent events.

Log image metadata, not the raw image, for debugging. Store file size, dimensions, and a hash alongside the request ID so you can reproduce issues without retaining potentially sensitive user images longer than necessary.

Watch your token usage per request. Image tokens add up faster than people expect, especially with multiple high-resolution images in one call. If you're on SubToAPI, the dashboard's usage metadata breaks down token consumption per application key, which makes it easy to spot a feature that's burning more budget than planned before it shows up as a surprise invoice. Check /pricing for how that fits into Solo, Team, and Scale plans.

If you want to get a vision endpoint running quickly without managing your own Anthropic account, key rotation, or billing reconciliation, SubToAPI gives you a sub_live_... key, the same /v1/messages request shape shown above, and per-key usage tracking out of the box. Start with /docs/quickstart or create an account at /signup.

Questions

Does Claude API vision require a different API key or endpoint than text requests? No. Vision uses the same /v1/messages endpoint and the same API key as text-only requests — you just add image blocks to the content array alongside text blocks.

What image formats and sizes does Claude's vision support? JPEG, PNG, GIF, and WebP are supported. There's no hard size limit you need to engineer around, but compressing images and keeping the longest edge near 1568px reduces token cost and latency without hurting analysis quality.

Can I send multiple images in a single request for comparison? Yes. Include multiple image blocks in one message's content array, and reference them by order or description in your text instruction — this works well for before/after comparisons or multi-page document analysis.