Image Input

Several IONOS CLOUD AI Model Hub endpoints accept images alongside text. This guide covers how to attach an image, which formats and sizes are accepted, and how images affect token cost.

Supported endpoints

Image input is available on the endpoints below. In every case, the model must advertise image input on its model card. Sending an image to an unsupported model returns a 400 error specifying the missing capability. For more information, see Models.

Endpoint	Part type	Guide
/v1/chat/completions	image_url	Text Generation
/v1/responses	input_image	Responses API
/v1/embeddings	image_url	Text Embeddings
/v1/rerank	image_url	Reranking
/v1/images/edits	url form field	Image Editing

Attach an image

Provide the image either as a publicly reachable HTTP or HTTPS URL, or as a base64 data URI inline in the request.

On chat completions, set the message content to an array of parts and pass the image as an image_url part:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "What does this diagram show?" },
    { "type": "image_url", "image_url": { "url": "data:image/webp;base64,[BASE64 IMAGE DATA]" } }
  ]
}

The Responses API names the part input_image and takes the URL directly:

{
  "role": "user",
  "content": [
    { "type": "input_text", "text": "What does this diagram show?" },
    { "type": "input_image", "image_url": "data:image/webp;base64,[BASE64 IMAGE DATA]" }
  ]
}

Embeddings and reranking use the same part names as chat completions. Image editing is a multipart/form-data request whose url field takes either form.

Accepted formats

• Any image/* type is accepted, including PNG, JPEG, and WebP.
• A data URI must carry a literal ;base64 parameter. A percent-encoded parameter is rejected.
• The declared type must match the part: an image_url part requires an image/ type.
• On chat completions, image_url parts are accepted on the user role only.

Request size limits

Limit	Value
Total request body	16 MiB
Each inline base64 data URI, after decoding	12 MiB
Content parts per message	2048

Exceeding one of these returns a 413 with a RESOURCE_LIMIT_ERROR. A remote URL keeps the image out of the request body, so it is the way to send media that does not fit.

The limits above apply only to payload size in bytes. Pixel dimensions are limited by the model rather than by the API, so check the model card for the largest resolution a model accepts. For more information, see Models.

Note: Concurrency limit on large requests applies. Requests larger than 4 MiB and requests sent with chunked transfer encoding are accepted six at a time. A further request is refused with a 503 and a Retry-After: 1 header.

For sustained image traffic, this limit is reached well before any size limit. Wait for the interval in Retry-After and resend, and keep individual requests below 4 MiB where possible. For more information, see Error Codes.

Token cost

Images count towards usage.prompt_tokens, which is what you are billed on. How an image is turned into tokens is a property of the model rather than the API, so refer to the model card for the exact rule. Two consequences hold across models:

• Images are processed at the resolution provided. Downscaling images before encoding is the most effective way to lower token costs.
• The detail field is accepted for compatibility, but it does not reliably reduce token usage or cost. Always downscale instead.

For a worked example of estimating image tokens against a context window, see the image size and token budget section in Reranking.

For document images specifically, a resolution of 200 DPI balances text sharpness against token cost. For more information, see Optical Character Recognition (OCR).

What you learned

In this guide, you learned how to:

1. Attach an image to a request on each endpoint that accepts one.
2. Recognize which image formats and encodings are accepted.
3. Size a request against the body, data URI, and concurrency limits.
4. Control the token cost of an image.