Справочник 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 не списывается и автоматически не списывается позже.
Идемпотентность: для защиты от повторных списаний на POST-маршрутах генерации поддерживается заголовок Idempotency-Key (или X-Idempotency-Key). Длина ключа — от 1 до 256 печатных ASCII-символов. Ключ изолирован в рамках профиля, API-ключа и семейства маршрутов. Повтор с тем же телом запроса возвращает сохранённый ответ с заголовком Idempotency-Replayed: true (кэш хранится 24 часа, после чего действует архивный период 7 дней с кодом result_expired) и ровно 0 дополнительных списаний с баланса. Подробности — в разделе Повторы и идемпотентность.

export NEXUS_API_KEY='ваш-ключ'
curl https://api.nexus-hub.tech/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 /api.json`	нигде	публичный OpenCode-compatible metadata catalog активных публичных моделей
`GET /v1/models`	нигде	список OpenAI-моделей, видимых ключу
`GET /v1/catalog`	нигде	публичные модели и проверенные endpoint capabilities
`GET /v1/models/catalog`	нигде	тот же публичный каталог, что `GET /v1/catalog`
`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-маршруты фильтруются по ключу, политике маршрута и доступу к модели.

OpenCode metadata catalog¶

GET /api.json не требует API-ключа. Публичный URL: https://api.nexus-hub.tech/api.json. Он возвращает актуальный список активных публичных моделей Nexus Hub и metadata, по которым OpenCode, Delta и совместимые клиенты выбирают транспорт (@ai-sdk/anthropic, @ai-sdk/openai или @ai-sdk/openai-compatible).

Это не гарантия доступа конкретного ключа. Наличие модели в /api.json означает только то, что модель сейчас активна и публична в общем каталоге Nexus Hub. Проверяйте key-specific доступ через авторизованный GET /v1/models. Публичный GET /v1/catalog остаётся каталогом capabilities и retail-цен. Для известных текстовых моделей каталог содержит подсказки о пределах контекста и вывода, а также текстовые модальности. Неизвестный предел обозначается 0; это не вводит нулевой лимит запросов в Nexus.

curl https://api.nexus-hub.tech/api.json

{"opencode":{"id":"opencode","name":"Nexus Hub","npm":"@ai-sdk/openai-compatible","api":"https://api.nexus-hub.tech/v1","models":{"grok-4.6":{"id":"grok-4.6","name":"Grok 4.6","family":"grok","attachment":false,"reasoning":true,"reasoning_options":[{"type":"effort","values":["low","medium","high","xhigh"]}],"tool_call":true,"temperature":true,"modalities":{"input":["text"],"output":["text"]},"limit":{"context":500000,"output":500000},"provider":{"npm":"@ai-sdk/openai-compatible"}}}}}

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

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

GET /v1/models/catalog — тот же публичный каталог, что и GET /v1/catalog, включая необязательный query 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.tech/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.tech/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.tech/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.tech/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, invalid_idempotency_key, idempotency_conflict, idempotency_in_progress, result_expired, а также коды лимитов 429 и емкости 503 (provider_capacity_exceeded и др.). Ошибки 429 и 503 сопровождаются заголовком Retry-After. При сетевых сбоях и таймаутах безопасно повторяйте запросы с заголовком Idempotency-Key. Подробности — в руководствах Ошибки и поддержка и Повторы и идемпотентность.