# Справочник API

Авторизация, версии путей, общие ограничения и коды ошибок API методов хаба.

Здесь собраны общие правила вызова API методов хаба и ссылки на справочники отдельных API.

## Авторизация

Для запросов с ключом хаба используйте заголовок:

```http
Authorization: Bearer sk-ci2-...
```

Один ключ подходит для разных API. В примерах ключ берется из переменной `COREINFRA_API_KEY`.

Anthropic Messages также принимает `x-api-key`, Google API — `x-goog-api-key`. Если такой заголовок присутствует, он имеет приоритет над `Authorization`. Исключения для вызовов без ключа указаны на страницах соответствующих API методов, например у [каталога OpenAI](https://coreinfra.ru/docs/reference/openai/models.md).

На [fal-совместимом API](https://coreinfra.ru/docs/reference/fal.md) ключ хаба передается в `Authorization: Key sk-ci2-...` или `Authorization: Bearer sk-ci2-...`, а скачивание готового видео по подписанной ссылке `/content?t=...` не требует заголовка авторизации.

При [подключении подписок](https://coreinfra.ru/docs/subscriptions.md) ключ хаба передается отдельно, в `x-coreinfra-api-key`, а токен подписки — в `Authorization: Bearer …`.

## Адреса и версии

Основной хост — `https://hub.coreinfra.ai`. Большинство API методов используют префикс `api/v1`. Google Interactions принимает `api/v1beta` и `api/v1`; оба пути вызывают одни и те же API методы. У [fal-совместимого API](https://coreinfra.ru/docs/reference/fal.md) (`/fal/api/...`) и у [проверки соединения Claude Code](https://coreinfra.ru/docs/reference/anthropic/api-hello.md) сегмент версии в пути отсутствует.

Используйте HTTP-метод и путь из справочника выбранного API. Незарегистрированное сочетание метода и пути возвращает статус-код `404`. Путь `/openai/api/v1/realtime` без WebSocket Upgrade (как и попытка открыть WebSocket по неподдерживаемому пути) возвращает статус-код `426`.

## Общие ограничения

На `hub.coreinfra.ai` HTTP-тело запроса ограничено 104 857 600 байтами (100 МиБ; на `/fal/api` — 64 МиБ). Для сжатого тела проверяются оба размера: до и после распаковки. Размер стартовой строки и заголовков HTTP/1-запроса ограничен 65 536 байтами (64 КиБ); на их чтение отводится 30 секунд.

Для POST-запросов к API методам поддерживается `Content-Encoding: gzip`, `deflate`, `br` или `zstd` (`identity` означает отсутствие сжатия). Несколько кодировок одновременно не принимаются. При неподдерживаемом сжатии возвращается ответ со статус-кодом `415` и заголовком `Accept-Encoding: gzip, deflate, br, zstd`.

Входные изображения и файлы передаются непосредственно в запросе: в кодировке base64 либо через `multipart/form-data` там, где API метод это поддерживает. Ссылки на внешние ресурсы и идентификаторы ранее загруженных файлов (`file_id`) отклоняются. Дополнительные ограничения описаны на странице [«Лимиты и ограничения»](https://coreinfra.ru/docs/limits.md).

## Общие ошибки

Формат тела ошибки зависит от вида ошибки: проверяйте статус-код, `Content-Type` и заголовки ответа. Ошибки валидации параметров запроса возвращаются в JSON-формате выбранного API (примеры приведены в справочнике каждого API). Ошибки недействительного ключа `sk-ci2-...`, недостатка средств, исчерпания недельного лимита расходов и блокировки модели возвращаются со статус-кодом `400` и типом `text/plain; charset=utf-8` (на [fal API](https://coreinfra.ru/docs/reference/fal.md) и [веб-API](https://coreinfra.ru/docs/reference/web.md) недействительный ключ возвращает статус-код `401`). Если заголовок авторизации отсутствует, пуст или имеет неверную схему, а также при неразбираемом теле на некоторых методах возвращается статус-код `400` с пустым телом.

| Статус-код | Причина                                                                                                | Что сделать                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`      | Отсутствует заголовок с ключом, неверна схема авторизации или ключ недействителен                      | Передайте действующий ключ `sk-ci2-...` в заголовке выбранного API                                                                         |
| `400`      | Некорректное тело запроса, неподдерживаемая модель, параметр или вложение                              | Проверьте страницу API метода и [каталог моделей](https://coreinfra.ru/docs/catalog.md)                                                    |
| `400`      | Доступный остаток равен нулю или отрицателен (`x-coreinfra-status: payment-required`)                  | [Пополните баланс](https://coreinfra.ru/docs/hub.md#balance)                                                                               |
| `400`      | Исчерпан недельный лимит расходов хаба, участника или ключа (`x-coreinfra-status: cost-limit-reached`) | Проверьте [лимиты](https://coreinfra.ru/docs/limits.md#spending) и [настройки команды](https://coreinfra.ru/docs/team-analytics.md#limits) |
| `400`      | Модель заблокирована белым списком хаба, участника или ключа                                           | Выберите разрешенную модель или обновите [список моделей](https://coreinfra.ru/docs/team-analytics.md#limits)                              |
| `401`      | Недействительный ключ (на fal API и веб-API) или отсутствует токен подписки                            | Проверьте переданный ключ или токен подписки                                                                                               |
| `403`      | Запрос отклонен провайдером модели по правилам контента или доступа                                    | Измените запрос или выберите другую модель                                                                                                 |
| `404`      | Сочетание HTTP-метода и пути не поддерживается либо ресурс не найден                                   | Сверьте полный адрес, HTTP-метод и идентификатор ресурса                                                                                   |
| `413`      | Тело запроса превышает допустимый размер                                                               | Уменьшите размер запроса (включая размер после распаковки)                                                                                 |
| `415`      | Неподдерживаемое сжатие тела запроса                                                                   | Используйте алгоритм из `Accept-Encoding` либо отправьте несжатое тело                                                                     |
| `422`      | Ошибка валидации входных параметров на [fal API](https://coreinfra.ru/docs/reference/fal.md)           | Проверьте поля `detail[].loc` и `detail[].msg` в ответе                                                                                    |
| `426`      | Некорректный заголовок WebSocket Upgrade или путь без поддержки WebSocket                              | Используйте API метод с поддержкой WebSocket и корректный Upgrade                                                                          |
| `429`      | Превышен лимит частоты запросов у провайдера модели                                                    | Повторите запрос позже с учетом заголовков `retry-after` / `retry-after-ms`                                                                |
| `499`      | Передача тела запроса прервалась                                                                       | Проверьте соединение и таймаут клиента                                                                                                     |
| `500`      | Внутренняя ошибка обработки запроса                                                                    | Повторите запрос позже                                                                                                                     |
| `502`      | Ошибка на стороне провайдера модели при выполнении запроса                                             | Повторите запрос позже либо выберите другую модель                                                                                         |
| `503`      | Провайдер модели временно недоступен                                                                   | Повторите запрос позже либо выберите другую модель                                                                                         |

## API

| API                        | Справочник                                                                                                       |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| OpenRouter-совместимый API | [Модели, изображения и видео](https://coreinfra.ru/docs/reference/openrouter.md)                                 |
| OpenAI API                 | [Текст, модели принятия решений, изображения, эмбеддинги и голос](https://coreinfra.ru/docs/reference/openai.md) |
| Anthropic API              | [Messages и подсчет токенов](https://coreinfra.ru/docs/reference/anthropic.md)                                   |
| Google API                 | [Interactions](https://coreinfra.ru/docs/reference/google.md)                                                    |
| xAI API                    | [Текстовые запросы](https://coreinfra.ru/docs/reference/xai.md)                                                  |
| TypeSafe API               | [System One](https://coreinfra.ru/docs/reference/typesafe.md)                                                    |
| fal API                    | [Очередь генерации видео FLUX 3 Max](https://coreinfra.ru/docs/reference/fal.md)                                 |
| Веб-поиск и чтение страниц | [Поиск и загрузка страниц](https://coreinfra.ru/docs/reference/web.md)                                           |

Бэкенды агентов описаны отдельно: [Codex](https://coreinfra.ru/docs/use/codex.md) и [Claude Code](https://coreinfra.ru/docs/use/claude.md).
