Перейти к содержанию

Поддерживаемые маршруты

Ниже перечислена публичная AI-поверхность. Она доступна только когда endpoint family и модель видимы авторизованному ключу. Примеры запросов и полный контракт ошибок находятся в справочнике API.

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

  • GET /v1/models
  • GET /v1/catalog — публичный каталог проверенных capabilities
  • GET /v1/models/{model}
  • GET /v1/balance
  • GET /v1/realtime — WebSocket upgrade с query model

OpenAI-compatible

  • POST /v1/chat/completions — JSON и SSE streaming
  • POST /v1/completions — строковый prompt, обычный JSON
  • POST /v1/responses — JSON и SSE streaming
  • POST /v1/responses/compact — JSON и SSE streaming
  • POST /v1/embeddings — JSON
  • POST /v1/rerank — JSON
  • POST /v1/moderations — JSON
  • POST /v1/images/generations — JSON, body до 1 MiB
  • POST /v1/images/edits — multipart, body до 25 MiB
  • POST /v1/images/variations — multipart, body до 25 MiB
  • POST /v1/audio/speech — JSON, body до 1 MiB, возможен binary response
  • POST /v1/audio/transcriptions — multipart, body до 25 MiB
  • POST /v1/audio/translations — multipart, body до 25 MiB

POST /v1/completions отклоняет batch- и token-id prompts с кодом unsupported_prompt_shape. Streaming недоступен для completions, embeddings, rerank и moderations.

Anthropic-compatible

  • POST /v1/messages — JSON и SSE streaming
  • POST /v1/messages/count_tokens — предварительный подсчёт без списания

Gemini-compatible

Discovery:

  • GET /v1beta/models
  • GET /v1beta/openai/models

Actions используют POST /v1beta/models/{model}:{action}:

  • generateContent — JSON generation
  • streamGenerateContent — SSE generation с финалом [DONE]
  • countTokens — JSON token count без списания
  • embedContent — один JSON embedding-запрос
  • batchEmbedContents — JSON-массив embedding-запросов

Gemini aliases фильтруются тем же key-specific каталогом, что и GET /v1/models. Если модель указана и в path, и в body, значения должны совпадать.

Общее поведение

Используйте Authorization: Bearer <key>, x-api-key или api-key. Для Gemini discovery также доступны x-goog-api-key и query-параметр key. Передавайте x-request-id для связи с поддержкой: он возвращается в заголовке ответа и локальном конверте ошибки.

Если протокол поддерживает лимит результата, задайте его явно: max_tokens, max_completion_tokens или max_output_tokens. Nexus не выводит лимит из размера body.

Подтверждённый usage успешного ответа может списываться один раз. При отсутствующем или противоречивом usage запрос остаётся без списания и не списывается позже автоматически. Совместимый fixed-price media response списывается только один раз после успешного ответа.

Как выбрать маршрут

  • Claude Code: POST /v1/messages;
  • Codex и response-клиенты: POST /v1/responses;
  • обычные OpenAI-клиенты: POST /v1/chat/completions;
  • Gemini-клиенты: generateContent или streamGenerateContent;
  • embeddings, reranking и moderation: отдельные JSON-маршруты;
  • media: соответствующий images/audio-маршрут;
  • Realtime: GET /v1/realtime.