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

Это справочник маршрутов, реализованных Nexus. Во всех примерах используется placeholder ключа и модель из каталога авторизованного ключа.

Общий контракт¶

Авторизация: Authorization: Bearer <key>, x-api-key и api-key. Gemini-маршруты также принимают x-goog-api-key и ?key=.
Где указывается модель: JSON body для OpenAI/Anthropic; {model} и суффикс action в пути Gemini; query model для Realtime.
Request ID: передавайте x-request-id; Nexus возвращает его в заголовке и локальном конверте ошибки.
Лимиты: обычный JSON до 32 MiB; Gemini JSON до 20 MiB; JSON image/audio до 1 MiB; multipart-загрузка image/audio до 25 MiB.
Списания: успешный подтверждённый usage или совместимый fixed-price ответ может списываться один раз. Отсутствующий или противоречивый usage не списывается и автоматически не списывается позже.

export NEXUS_API_KEY='ваш-ключ'
curl https://api.nexus-hub.ru/v1/models \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "x-request-id: docs-models-001"

Успешный ответ каталога имеет такую форму:

{"object":"list","data":[{"id":"MODEL","object":"model","created":0,"owned_by":"..."}]}

Локальные ошибки используют единый безопасный конверт:

{"error":{"message":"model is not enabled for this API key","type":"nexus_error","code":"model_not_allowed","request_id":"docs-001"}}

Каталог и баланс¶

Метод и путь	Где указывается модель	Успешный ответ
`GET /v1/models`	нигде	список OpenAI-моделей, видимых ключу
`GET /v1/catalog`	нигде	публичные модели и проверенные endpoint capabilities
`GET /v1/models/{model}`	path	одна видимая модель или `model_not_found`
`GET /v1/balance`	нигде	объект баланса профиля ключа
`GET /v1beta/models`	нигде	Gemini aliases, методы и доступные лимиты токенов
`GET /v1beta/openai/models`	нигде	OpenAI-подобный список Gemini для bridge-клиентов
`GET /v1/catalog?currency=RUB\\|USD\\|EUR\\|CNY`	нигде	публичный retail-каталог и снимок цен

Авторизованные discovery-маршруты фильтруются по ключу, политике маршрута и доступу к модели.

Публичный каталог¶

GET /v1/catalog не требует API-ключа и по умолчанию возвращает RUB. Параметр currency принимает USD, EUR и CNY. Неизвестное значение возвращает 400 с кодом invalid_catalog_currency.

Ответ сохраняет порядок активного публичного каталога, его семейства, публичные ID и отображаемые названия моделей, endpoint families, billing mode и компоненты конечной retail цены. Это не ответ о доступности для конкретного ключа: для неё используйте авторизованный GET /v1/models. Каждая денежная величина — decimal string с явной единицей, например USD_per_1M_tokens или EUR_per_request. snapshot.fx_status принимает current, stale или unavailable; при unavailable затронутые компоненты будут null, а не значениями RUB под меткой выбранной валюты.

{"snapshot":{"fetched_at":"2026-08-14T10:00:00Z","effective_date":"2026-08-14","fx_status":"current"},"currency":"EUR","families":[{"id":"example","models":[{"id":"MODEL","display_name":"MODEL","endpoint_families":["responses"],"prices":[{"endpoint_families":["responses"],"billing_mode":"per_token","components":{"input":{"amount":"1.250000","unit":"EUR_per_1M_tokens"},"cached_input":null,"cache_write":null,"output":{"amount":"5.000000","unit":"EUR_per_1M_tokens"},"request":null}}]}]}]}

Маршрут предназначен для таблицы в документации. Он поддерживает browser cache revalidation через ETag и имеет короткое публичное cache-время.

GET /v1/catalog — no-auth endpoint для discovery capabilities. Он содержит только публичные метаданные моделей и проверенные optional-параметры; отсутствие endpoint-записи остаётся unknown и не превращается в запрет.

Генерация текста¶

Все строки ниже принимают JSON до 32 MiB. Используйте модель из каталога ключа.

Метод и путь	Минимальное JSON body	Успешный ответ	Streaming и лимит результата
`POST /v1/chat/completions`	`{"model":"MODEL","messages":[{"role":"user","content":"Reply OK"}],"max_completion_tokens":16}`	OpenAI Chat object	`stream: true`; `max_completion_tokens` или `max_tokens`
`POST /v1/completions`	`{"model":"MODEL","prompt":"Reply OK","max_tokens":16}`	OpenAI completion object	без stream; `max_tokens`
`POST /v1/responses`	`{"model":"MODEL","input":"Reply OK","max_output_tokens":16}`	Responses object	`stream: true`; `max_output_tokens`
`POST /v1/responses/compact`	`{"model":"MODEL","input":"Reply OK","max_output_tokens":16}`	compact Responses object	`stream: true`; `max_output_tokens`
`POST /v1/messages`	`{"model":"MODEL","max_tokens":16,"messages":[{"role":"user","content":"Reply OK"}]}`	Anthropic Messages object	`stream: true`; нужен положительный `max_tokens`
`POST /v1/messages/count_tokens`	`{"model":"MODEL","messages":[{"role":"user","content":"Reply OK"}]}`	`{"input_tokens":...}`	без списания и stream

На оба Messages-маршрута передавайте anthropic-version: 2023-06-01. JSON streaming использует нативные SSE terminal events, а обычный запрос возвращает один JSON-объект. /v1/completions принимает только строковый prompt: batch- и token-ID prompts возвращают unsupported_prompt_shape.

Минимальный запрос Responses:

curl https://api.nexus-hub.ru/v1/responses \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_FROM_V1_MODELS","input":"Reply exactly OK.","max_output_tokens":16}'

Минимальный запрос Messages:

curl https://api.nexus-hub.ru/v1/messages \
  -H "x-api-key: $NEXUS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_FROM_V1_MODELS","max_tokens":16,"messages":[{"role":"user","content":"Reply exactly OK."}]}'

Embeddings, ranking и moderation¶

Эти JSON-маршруты принимают до 32 MiB и не поддерживают streaming.

Метод и путь	Минимальное JSON body	Успешный ответ
`POST /v1/embeddings`	`{"model":"MODEL","input":"Reply OK"}`	список embeddings
`POST /v1/rerank`	`{"model":"MODEL","query":"OK","documents":["OK"],"top_n":1}`	результаты ранжирования
`POST /v1/moderations`	`{"model":"MODEL","input":"Reply OK"}`	результаты moderation

Ключу нужен доступ к endpoint family и модели.

Images и audio¶

Метод и путь	Минимальные поля запроса	Лимит и успешный ответ
`POST /v1/images/generations`	JSON: `model`, `prompt`	1 MiB; JSON image result
`POST /v1/images/edits`	multipart: `model`, `image`, `prompt`	25 MiB; JSON image result
`POST /v1/images/variations`	multipart: `model`, `image`	25 MiB; JSON image result
`POST /v1/audio/speech`	JSON: `model`, `input`, `voice`	1 MiB; binary audio
`POST /v1/audio/transcriptions`	multipart: `model`, `file`	25 MiB; JSON transcript
`POST /v1/audio/translations`	multipart: `model`, `file`	25 MiB; JSON translation

Media-маршруты не поддерживают streaming. Неверный тип возвращает unsupported_content_type, слишком большой body — payload_too_large.

Gemini-compatible actions¶

Путь имеет вид POST /v1beta/models/{model}:{action}. Все action body принимают до 20 MiB. Модель находится в path; если она также есть в body, значения должны совпадать.

Action	Минимальная форма запроса	Ответ/stream и лимит результата
`generateContent`	`contents`; при необходимости `generationConfig`	JSON; `generationConfig.maxOutputTokens`
`streamGenerateContent`	та же	SSE chunks, финал `[DONE]`; то же поле лимита
`countTokens`	`contents`	`{"totalTokens":...}`; без списания и stream
`embedContent`	`content`	один JSON embedding; без stream
`batchEmbedContents`	`requests[]`	JSON embeddings; без stream

curl "https://api.nexus-hub.ru/v1beta/models/MODEL:generateContent" \
  -H "x-goog-api-key: $NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Reply exactly OK."}]}],"generationConfig":{"maxOutputTokens":16}}'

countTokens — предварительная проверка и не меняет баланс. embedContent принимает один content, batchEmbedContents — массив requests.

Лимит body и лимит output-токенов независимы. Когда для модели задан явный лимит, превышение max_tokens, max_completion_tokens, max_output_tokens или Gemini generationConfig.maxOutputTokens возвращает invalid_request_error. Gemini discovery показывает outputTokenLimit, если такие metadata настроены; отсутствие значения не создаёт скрытый default.

Realtime WebSocket¶

Подключайтесь к wss://api.nexus-hub.ru/v1/realtime?model=MODEL_FROM_V1_MODELS и передавайте ключ Authorization: Bearer или x-api-key в handshake. Модель из query фиксирована на всю сессию; попытка заменить её отклоняется. Текстовые, binary, ping, pong и close frames проксируются. Output limits внутри протокола передаются без изменений.

Ошибки и повторы¶

Основные коды: invalid_key, model_not_found, model_not_allowed, endpoint_not_allowed, insufficient_balance, streaming_not_supported, unsupported_content_type, payload_too_large, upstream_error, upstream_timeout, pricing_unavailable, duplicate_request_id. Повторяйте только временные ошибки по политике клиента и сообщайте request ID в поддержку. Не повторяйте вслепую запрос после возможной доставки ответа. Подробности — в ошибках и поддержке.