## Анализ изображений

Модели с поддержкой изображений принимают графику через массив `content` с элементом `type: "image_url"`. Адрес изображения — либо `data:`-URI с данными в base64, либо ссылка `https`. В каталоге [`GET /v1/models`](/docs/ai/models/list) такие модели имеют флаг `capabilities.vision: true`.

Бесплатно изображения обрабатывают `bitrix/bitrixgpt-5.5` и `bitrix/bitrixgpt-5.5-thinking`. Через свой ключ провайдера (BYOK) доступны модели Anthropic Claude: `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `anthropic/claude-haiku-4-5-20251001`. Для них платформа сама приводит элемент `image_url` к формату Anthropic — на стороне клиента менять ничего не нужно.

## Пример запроса

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/chat/completions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/bitrixgpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Опиши, что на изображении"},
          {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."}}
        ]
      }
    ],
    "max_tokens": 500
  }'
```

## Ограничения

| Параметр | Значение |
|----------|----------|
| MIME-типы | `image/png`, `image/jpeg`, `image/gif`, `image/webp` |
| Максимум на изображение, декодированный размер | 20 MiB |
| Максимум `image_url.url` в запросе | 30 MiB, с запасом на кодирование base64 это 22 MiB полезных данных |
| Формат `url` | `data:<mime>[;параметр=значение]*;base64,<данные>` или `https://<host>/<path>`. Параметры между типом и `;base64` (например `data:image/jpeg;name=photo.jpg;base64,…`) допускаются и отбрасываются |
| Ссылки `http://` | не принимаются, только `https` или `data:` |
| Максимум элементов `content` на сообщение | 64 |
| Максимум тела запроса на эндпоинт | 30 MiB |

**MiB** — мебибайт, двоичная единица по стандарту IEC 80000-13: `1 MiB = 2²⁰ = 1 048 576 байт ≈ 1,05 МБ`. Лимиты проверяются как `N × 1024 × 1024`, поэтому и в сообщении об ошибке размер указан в `MiB` — например, `decoded size 21.3 MiB exceeds limit 20 MiB`.

## Проверка содержимого

Перед отправкой модели содержимое каждого элемента `image_url`, переданного как `data:`-URI, проверяется по фактическим байтам, а не по заявленному MIME-типу. Если содержимое не является изображением — например HTML-страница или ответ с ошибкой, закодированные в base64 и объявленные как `image/png`, — элемент не отбрасывается, а **заменяется на своей позиции** текстовой заглушкой `[image unavailable: <причина>]`. Остальные изображения обрабатываются как обычно, запрос завершается успешно.

Проверка по содержимому применяется только к `data:`-URI. Кандидат по ссылке `https://` платформа передаёт модели как есть, без загрузки и проверки байтов, — такие ссылки валидируйте на своей стороне.

Позиции элементов сохраняются: длина массива `content` не меняется, поэтому нумерация кандидатов на вашей стороне остаётся верной.

Факт замены виден в ответе:

- заголовок `X-Image-Parts-Rejected` несёт число заменённых элементов — это единый сигнал для всех режимов ответа; для потоковых ответов он приходит вместе с началом потока;
- в обычном (не потоковом) ответе поле `warnings` дополнительно содержит запись с кодом `IMAGE_CONTENT_REJECTED` и деталями замен. В потоковом ответе поля `warnings` нет — ориентируйтесь на заголовок.

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `invalid_image_payload` | Структурная ошибка запроса: отсутствует поле `url`, строка не является ни URL, ни data-URI, бесформенный data-URI (без `;base64,`), неподдерживаемая схема или `http://` в production. Сообщение содержит номер элемента `content` и конкретную причину |

Ошибки содержимого (не изображение, повреждённый base64, неподдерживаемый MIME-тип, превышение 20 MiB) **больше не завершают запрос ошибкой** — такой элемент заменяется заглушкой (см. «Проверка содержимого»).

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Массив `content` нужен только для изображений.** Для текстовых запросов передавайте `content` строкой. Массив с единственным элементом `text` тоже работает, но избыточен.

**Размер проверяется после декодирования.** Ограничение в 20 MiB относится к самому изображению, а не к строке base64. Строка длиннее примерно на треть, поэтому тело запроса ограничено 30 MiB.

## Смотрите также

- [Создать чат-комплишен](./completions.md)
- [Список моделей](/docs/ai/models/list)
- [Свои ключи (BYOK)](/docs/ai/credentials)