> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/image-input.md).

# Image Input

Several <code class="expression">space.vars.ionos\_cloud\_ai\_model\_hub</code> 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 [<mark style="color:blue;">Models</mark>](/cloud/ai/ai-model-hub/models.md).

| Endpoint               | Part type        | Guide                                                                                                 |
| ---------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
| `/v1/chat/completions` | `image_url`      | [<mark style="color:blue;">Text Generation</mark>](/cloud/ai/ai-model-hub/how-tos/text-generation.md) |
| `/v1/responses`        | `input_image`    | [<mark style="color:blue;">Responses API</mark>](/cloud/ai/ai-model-hub/how-tos/responses.md)         |
| `/v1/embeddings`       | `image_url`      | [<mark style="color:blue;">Text Embeddings</mark>](/cloud/ai/ai-model-hub/how-tos/text-embeddings.md) |
| `/v1/rerank`           | `image_url`      | [<mark style="color:blue;">Reranking</mark>](/cloud/ai/ai-model-hub/how-tos/reranking.md)             |
| `/v1/images/edits`     | `url` form field | [<mark style="color:blue;">Image Editing</mark>](/cloud/ai/ai-model-hub/how-tos/image-edits.md)       |

## 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:

```json
{
  "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:

```json
{
  "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 [<mark style="color:blue;">Models</mark>](/cloud/ai/ai-model-hub/models.md).

{% hint style="info" %}
**Note:** Concurrency limit on large requests applies. Requests larger than 4 MiB and requests sent with chunked transfer encoding are accepted two 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 [<mark style="color:blue;">Error Codes</mark>](/cloud/ai/ai-model-hub/error-codes.md).
{% endhint %}

## 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 [<mark style="color:blue;">Reranking</mark>](/cloud/ai/ai-model-hub/how-tos/reranking.md).

For document images specifically, a resolution of 200 DPI balances text sharpness against token cost. For more information, see [<mark style="color:blue;">Optical Character Recognition (OCR)</mark>](/cloud/ai/ai-model-hub/how-tos/ocr.md).

## 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/image-input.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.