# Известные ограничения

Список того, что сейчас работает не так, как можно ожидать от OpenAI-совместимого API.
Написан честно, чтобы вы не отлаживали чужие баги как свои.

## Мультимодальный ввод не поддерживается

Поле `content` в сообщении принимает **только строку**. Массив блоков, которым OpenAI
передаёт изображения, отклоняется валидацией:

```json
{
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Что на картинке?"},
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
    ]
  }]
}
```

```json
{
  "statusCode": 400,
  "message": ["content must be a string"],
  "error": "Bad Request"
}
```

Следствие: vision-возможности недоступны даже у моделей, которые их поддерживают, а
плагины с прикреплением скриншотов (Cline, Roo Code, Continue) не смогут отправить
изображение.

**Обходного пути на стороне API нет.** Описывайте изображение текстом либо распознавайте
его отдельным сервисом.

## `/v1/ai/responses` не умеет стриминг

Параметр `stream` принимается без ошибки, но **игнорируется** — ответ всегда приходит
целиком. Клиент, ожидающий поток, будет ждать полной генерации.

Для стриминга используйте [Chat Completions](https://agentapi.ru/docs/endpoints/chat-completions) или
[Messages](https://agentapi.ru/docs/endpoints/messages).

## `stop_sequences` в `/v1/ai/messages` не применяется

Поле парсится и проходит валидацию, но до провайдера не доходит — генерация не
остановится на указанной последовательности.

Обход: используйте `stop` в [Chat Completions](https://agentapi.ru/docs/endpoints/chat-completions), где
параметр работает, либо обрезайте ответ на своей стороне.

## Путь Anthropic-эндпоинта нестандартный

Эндпоинт находится по адресу `/v1/ai/messages`, а не `/v1/messages`. Клиенты, жёстко
дописывающие `/v1/messages` к базовому URL (Claude Code, `client.messages.create()` в
Anthropic SDK), напрямую не подключаются.

Рабочие варианты описаны в [Claude Code и Anthropic SDK](https://agentapi.ru/docs/integrations/claude-code).

## Нет списка моделей во внешнем API

Эндпоинта `GET /v1/ai/models` не существует. Плагины и клиенты, подтягивающие модели
автоматически, покажут пустой список — слаг вводится вручную.

Список моделей доступен через `GET /models` (без префикса `/v1`, ключ не требуется),
но этот путь не соответствует ожиданиям OpenAI-клиентов. См. [Модели](https://agentapi.ru/docs/models).

## Ошибка внутри стрима приходит пустой

Если генерация оборвалась после начала стриминга, кадр с ошибкой может не содержать
текста сообщения:

```
data: {"error":{"message":{}}}
```

Причина — сериализация объекта ошибки. HTTP-статус при этом уже 200, поскольку заголовки
отправлены до первого токена.

Практический вывод: проверяйте **наличие** поля `error` в кадрах и не рассчитывайте на
информативный текст. Причину смотрите по коду ответа при повторе того же запроса без
`stream`.

## Формат ошибок отличается от OpenAI

Ответ не обёрнут в объект `error` с полями `type` и `code`:

```json
{ "statusCode": 401, "message": "Invalid or inactive API key", "error": "Unauthorized" }
```

Ошибки провайдера (502) приходят в третьем формате — вообще без `statusCode`:

```json
{ "message": "Provider returned error: model not found" }
```

Библиотеки, разбирающие OpenAI-формат ошибок, покажут текст, но не определят тип.
См. [Ошибки и лимиты](https://agentapi.ru/docs/errors).

## Rate limit считается по IP

60 запросов в минуту привязаны к IP-адресу, **не** к API-ключу. Следствия:

- Несколько сервисов за одним NAT или на одном сервере делят общий лимит.
- Создание дополнительных ключей не увеличивает пропускную способность.
- Ограничение нельзя поднять на уровне аккаунта.

Исключение — `POST /v1/ai/embeddings`, он не лимитируется.

## Статистика только по аккаунту

Расходы агрегируются по пользователю; разбивки по отдельным ключам нет. Чтобы разделять
затраты по проектам, передавайте `session_id` или `metadata` в запросах и считайте на
своей стороне.

## Rerank не поддерживается

Эндпоинта переранжирования нет. В Continue и Roo Code не назначайте роль `rerank`.

---

Если какое-то из ограничений блокирует ваш сценарий — напишите на
[agent@agentapi.ru](mailto:agent@agentapi.ru).