Vision: sending images to models

Vision means sending an image to a model and asking about it: a screenshot of an error, a diagram, a photo of a whiteboard. On Tokens images travel inside the normal chat request, on POST https://tokens.bd/v1/chat/completions as image_url content parts and on POST https://tokens.bd/v1/messages as image content blocks. The gateway carries the image to the provider and bills what the provider reports. Whether the model can read the image is up to the model.

Tokens has no separate image endpoint. Image generation, file uploads and the Anthropic Files API are not served (see Models and usage). This page is about image input only.

Check that the model accepts images#

Not every model reads images. The model catalog at /models records the context window, prices and a description for each model, but it has no field that says "supports images". To find out:

• Read the model's description on its /models page and the maker's own documentation for the model.
• See the vision section of Choosing a model, which lists several models by what they accept.
• Send one small test image (the examples below) and ask "What is in this image?". A model that reads images answers about the picture.

A text-only model does not always fail loudly. The provider decides: it can return a 400 (which reaches you as invalid_request, see errors), or it can drop the image and answer from the text alone. If the answer ignores the picture, treat that as "this model does not take images".

Chat Completions: image_url parts#

Put an array in the message content instead of a string. Each element is a text part or an image_url part. The url is either a public https URL or a base64 data URL (data:<media type>;base64,<data>).

{
  "role": "user",
  "content": [
    { "type": "text", "text": "What does this error screenshot say?" },
    {
      "type": "image_url",
      "image_url": { "url": "data:image/png;base64,<BASE64_DATA>", "detail": "auto" }
    }
  ]
}

detail is OpenAI's optional hint (low, high or auto; auto when omitted). Other providers may ignore it, and the gateway drops it when it has to translate the request for an Anthropic-style provider (see below).

curl https://tokens.bd/v1/chat/completions \
  -H "Authorization: Bearer $TOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4.1-flash",
    "max_tokens": 300,
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "image_url", "image_url": {"url": "https://YOUR-HOST/path/to/image.png"}},
          {"type": "text", "text": "Describe this image in two sentences."}
        ]
      }
    ]
  }'

import base64
import os
from openai import OpenAI

client = OpenAI(base_url="https://tokens.bd/v1", api_key=os.environ["TOKENS_API_KEY"])

with open("screenshot.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode("ascii")

resp = client.chat.completions.create(
    model="deepseek/deepseek-v4.1-flash",
    max_tokens=300,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
                {"type": "text", "text": "Describe this image in two sentences."},
            ],
        }
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://tokens.bd/v1", apiKey: process.env.TOKENS_API_KEY });

const b64 = fs.readFileSync("screenshot.png").toString("base64");

const resp = await client.chat.completions.create({
  model: "deepseek/deepseek-v4.1-flash",
  max_tokens: 300,
  messages: [
    {
      role: "user",
      content: [
        { type: "image_url", image_url: { url: `data:image/png;base64,${b64}` } },
        { type: "text", text: "Describe this image in two sentences." },
      ],
    },
  ],
});
console.log(resp.choices[0].message.content, resp.usage);

Replace https://YOUR-HOST/path/to/image.png with a link to an image you control. The media type in a data URL must match the file (image/png, image/jpeg, image/webp, image/gif).

Messages: image content blocks#

On /v1/messages an image is a content block with a source. Two source types work through Tokens:

{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": { "type": "base64", "media_type": "image/png", "data": "<BASE64_DATA>" }
    },
    { "type": "text", "text": "What does this error screenshot say?" }
  ]
}

{
  "type": "image",
  "source": { "type": "url", "url": "https://YOUR-HOST/path/to/image.png" }
}

data is the raw base64 string with no data: prefix. Anthropic's third source, {"type": "file", "file_id": "..."}, needs their Files API, which Tokens does not serve. Send the image itself.

curl https://tokens.bd/v1/messages \
  -H "x-api-key: $TOKENS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4.1-flash",
    "max_tokens": 300,
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "image", "source": {"type": "url", "url": "https://YOUR-HOST/path/to/image.png"}},
          {"type": "text", "text": "Describe this image in two sentences."}
        ]
      }
    ]
  }'

import base64
import os
import anthropic

client = anthropic.Anthropic(base_url="https://tokens.bd", api_key=os.environ["TOKENS_API_KEY"])

with open("screenshot.png", "rb") as f:
    b64 = base64.standard_b64encode(f.read()).decode("ascii")

message = client.messages.create(
    model="deepseek/deepseek-v4.1-flash",
    max_tokens=300,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": b64}},
                {"type": "text", "text": "Describe this image in two sentences."},
            ],
        }
    ],
)
print(message.content[0].text)
print(message.usage)

import fs from "node:fs";
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ baseURL: "https://tokens.bd", apiKey: process.env.TOKENS_API_KEY });

const b64 = fs.readFileSync("screenshot.png").toString("base64");

const message = await client.messages.create({
  model: "deepseek/deepseek-v4.1-flash",
  max_tokens: 300,
  messages: [
    {
      role: "user",
      content: [
        { type: "image", source: { type: "base64", media_type: "image/png", data: b64 } },
        { type: "text", text: "Describe this image in two sentences." },
      ],
    },
  ],
});
console.log(message.content[0], message.usage);

Anthropic's guidance is to put images before the text that asks about them, and to label several images in the text ("Image 1:", "Image 2:") so you can refer to them. Earlier images in a conversation stay visible to the model, but you must resend them in every request, because the API is stateless.

Base64 from the command line#

A base64 image is too large to type into a curl -d '...' argument. Write the request to a file and send the file. On macOS and Linux, with jq installed:

base64 screenshot.png | tr -d '\n' > screenshot.b64

jq -n --rawfile img screenshot.b64 '{
  model: "deepseek/deepseek-v4.1-flash",
  max_tokens: 300,
  messages: [{
    role: "user",
    content: [
      {type: "image_url", image_url: {url: ("data:image/png;base64," + $img)}},
      {type: "text", text: "Describe this image in two sentences."}
    ]
  }]
}' > request.json

curl https://tokens.bd/v1/chat/completions \
  -H "Authorization: Bearer $TOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

What the gateway does with images#

On a native request (the provider speaks the same format as your request) the gateway forwards the body and changes only the model field (plus a usage-reporting option on streamed Chat Completions). It does not decode, resize or inspect the image.

Some models are only available from a provider that speaks the other format. Then the gateway translates, and images are handled like this:

The same translation rules, and the other fields that are carried across, are described in Messages.

Size limits#

Two limits matter, and the smaller one wins.

Tokens: the whole request body can be at most 10 MB, otherwise the gateway answers 413 request_entity_too_large. Base64 makes data about a third larger than the file, so all images in one request together can be roughly 7 MB of image files at most, and less once the text and earlier conversation turns are counted. Every request resends the full conversation, including earlier images.

The provider: each provider has its own limits on image formats, dimensions, count and size per image. As checked in October 2026:

• Anthropic: JPEG, PNG, GIF (first frame only) and WebP; up to 8000 x 8000 pixels per image; 10 MB per image (base64); up to 100 images per request on models with a 200K-token context window and 600 on others. Above 20 images in one request a stricter per-image pixel limit applies, and Anthropic suggests keeping each side to 2000 px. Source: Anthropic vision documentation.
• OpenAI: PNG, JPEG, WebP and non-animated GIF; up to 1,500 images per request. Source: OpenAI images and vision guide. OpenAI's 512 MB payload limit is above Tokens' 10 MB, so the Tokens limit applies first.
• Other makers publish their own limits. Check the maker's documentation for the model you use.

Resize large photos before sending. A phone photo is often 4000 pixels wide, and models downscale it anyway, so you pay for upload size and latency without gaining detail. Keep text in screenshots legible: very aggressive JPEG compression makes small text unreadable.

How image input is billed#

An image is converted to input tokens by the provider, and the provider reports the total in usage. Tokens bills that reported input count at the model's input price, like any other input. Roughly, providers count images in patches: Anthropic documents ceil(width / 28) x ceil(height / 28) tokens per image before downscaling to a cap (about 1,568 tokens on its standard tier, up to 4,784 on its high-resolution tier). OpenAI documents patch-based and tile-based counts that depend on the model and on detail. Other makers differ, so read usage from a test request to see the real cost for your model.

Admission works from a different number. Before forwarding a request the gateway reserves its worst-case cost against your balance, and it estimates the input side as one token per four characters of the request body. A large base64 image is a lot of characters, so the reservation for a request with a multi-megabyte image can be far above what the provider ends up charging. You are charged the real usage, not the reservation, but a low balance or a key close to its spend cap can be refused with insufficient_credits or monthly_spend_cap_exceeded for a request that would have cost very little. Resizing the image fixes both the cost and the refusal. See the reservation notes in Chat Completions.

Troubleshooting#

If the error does not say what is wrong, the upstream message is replaced with a generic one. Send the x-tokens-request-id to support, and see errors for the codes.