Skip to content
Claudexia TeamAPI

Images in the API: formats, resolution, and what does not work

How to send pictures to the model correctly, what resolution costs in tokens, where vision genuinely handles OCR, and where the model reliably gets it wrong.

The model accepts a picture almost the same way it accepts text: you add an image block to the message, then ask about its content. The difference is in the details that decide whether it works well or not.

How to send an image

Two options: base64-encode the file and embed it directly in the request body, or point to a public URL. Base64 is more reliable because it does not depend on a third-party server being reachable at the moment the request is processed.

Python example with the Anthropic SDK:

import base64
import anthropic

client = anthropic.Anthropic(
    api_key="your-claudexia-key",
    base_url="https://api.claudexia.tech/v1",
)

with open("receipt.jpg", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-sonnet-4.6",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": image_data}},
            {"type": "text", "text": "Pull the total, date, and line items from this receipt"},
        ],
    }],
)

JPEG, PNG, GIF, and WebP are supported. PDF goes in as its own block type rather than an image, useful when you need to parse a whole document rather than a single page screenshot.

Resolution and cost

An image is billed in tokens the same way text is, but the rule is different: cost scales with the area of the picture, not with how visually complex it is. A photo shot at a phone's maximum resolution and the same photo shrunk down to a size where the text is still readable cost different amounts, and the recognition result is often identical.

The practical takeaway: compress the image to the size the task actually needs before sending it. A side of a bit over a thousand pixels is enough to read text off a receipt or screenshot; for fine print it makes sense to raise resolution selectively rather than bumping it for an entire batch of requests.

If a single request needs to parse several images, each one is billed separately and the total cost scales linearly. For batches of dozens of images that adds up fast, worth estimating ahead of time with the calculator on the site.

OCR tasks where vision does well

Extracting structured data from receipts, invoices, and forms. The model finds fields like total, date, and document number reliably even when the layout differs from one receipt to the next, because it reads context rather than matching a fixed pattern of coordinates.

Parsing tables from screenshots. If a table is readable by eye, the model usually maps rows and columns correctly and hands the result back as JSON with no extra markup needed.

Handwritten text reads noticeably worse than print, but legible handwriting is recognized far better than classic OCR built on fixed character templates.

What does not work well

Precise object coordinates in an image. The model can tell you there is a "Submit" button in the photo, but its answer about the exact pixel coordinates of that button is often off. For interface automation that needs a precise click, relying on model-provided coordinates is risky.

Counting objects in a crowded frame. On a photo with a dozen similar items the model regularly misses the count by one or two, especially when objects partially overlap.

Small text in a low-resolution image or poor lighting. A stronger model does not fix this, a better scan or photo does.

Comparing two similar images for small differences: the model tends to invent differences that are not there unless you explicitly ask it to be conservative and admit uncertainty.

Preparing images before sending

Crop out the excess margin around the part you need, this cuts cost and removes noise that can throw the model off. Boosting contrast on a scanned document with light background often improves accuracy more noticeably than raising resolution.

If a document spans several pages, send them one at a time with an explicit page number in the prompt text rather than stitching them into one long image. The model handles a set of reasonably sized frames better than one very elongated image.

Where the Anthropic and OpenAI formats differ

Anthropic represents an image as its own {"type": "image", "source": {...}} block inside the content array. OpenAI uses a different shape: {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}. Both work through Claudexia against their respective endpoints, so only the block structure changes, not the logic of the request itself.

In short

Base64 is more reliable than links, compress the image to what the task needs rather than sending the raw file straight off a phone. Vision does well at structured OCR: receipts, forms, tables, but poorly at exact coordinates and counting objects in a crowded frame. For small text, the fix is usually a better photo, not a stronger model.