← на главную

API reference

Совместим с OpenAI и Anthropic SDK. base URL .

Аутентификация

Кабинет — JWT (Bearer). API — выдаваемый ключ sk_live_….

POST /api/v1/auth/register

curl -X POST /api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@x.y","password":"...","name":"Alice"}'

POST /api/v1/auth/login

Возвращает access_token (JWT, 7 дней). После 5 неудач за 15 мин — 429 + retry_after_sec.

curl -X POST /api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"you@x.y","password":"..."}'

GET /api/v1/auth/meJWT

GET /api/v1/auth/preferencesJWT

blend_enabled, blend_aggressiveness (low|medium|high).

PATCH /api/v1/auth/preferencesJWT

API-ключи

GET /api/v1/api-keysJWT

POST /api/v1/api-keysJWT

Тело: { name, rate_limit_rpm?, credit_cap_kop? }. Сам ключ возвращается только при создании.

PATCH /api/v1/api-keys/:idJWT

DELETE /api/v1/api-keys/:idJWT

Chat completions (OpenAI-совместимо)

Полностью совместим с openai.chat.completions.create() — подмени baseURL и ключ.

POST /api/v1/chat/completionsAPI key

curl -X POST /api/v1/chat/completions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Привет"}]
  }'

Заголовки ответа: X-AiMost-Served-Model, X-AiMost-Backend (own/direct/openrouter/cache), X-AiMost-Blend-Reason, X-AiMost-Cache-Level (hit-l1/miss), X-AiMost-Saved-Kop.

Заголовки запроса: X-AiMost-Blend: off — отключить smart-blend на этот вызов.

Streaming через SSE: "stream": true — формат как у OpenAI.

Anthropic Messages

POST /api/v1/messagesAPI key

Совместим с anthropic.messages.create(). Поддерживает image content blocks, tools/tool_use/tool_result, streaming SSE (input_json_delta для tool_calls).

Embeddings / audio / rerank / video

POST /api/v1/embeddingsAPI key

POST /api/v1/audio/speechAPI key

POST /api/v1/rerankAPI key

POST /api/v1/video_generationsAPI key

Эти роуты — passthrough к upstream (через resolver), биллинг ведётся как обычно.

OAuth (Cursor / Cline / aider integration)

Минимальный flow: внешнее приложение редиректит юзера на /oauth/consent?callback_url=...&state=..., юзер approve'ит, мы создаём ключ и code (TTL 5 мин), редиректим обратно с ?code=..., внешнее приложение обменивает code → key.

POST /api/v1/oauth/authorizeJWT

Body: { callback_url, state?, key_name? }. Вызывается из web/oauth/consent после клика Approve.

POST /api/v1/oauth/token

curl -X POST /api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"code":"oac_...", "callback_url":"https://your.app/cb"}'

Усреднение / биллинг / лог

GET /api/v1/creditsJWT

GET /api/v1/generationsJWT

Page: ?page=1&per_page=20 (max 100).

GET /api/v1/generations/:idJWT

GET /api/v1/generations.csvJWT

CSV-выгрузка лога.

GET /api/v1/usage/summaryJWT

Дневная агрегация для графика. Параметр ?days=30 (1..90).

Пополнения

GET /api/v1/depositsJWT

История пополнений баланса (метод, сумма в копейках, статус, дата).

Боевой webhook ЮKassa подключается на этапе интеграции с платёжным провайдером. Эндпоинт документируется отдельно после готовности.

Каталог моделей

GET /api/v1/models

Публичный (без auth). Возвращает все активные модели с тарифами в копейках за 1M токенов (input/output), context length, флаги tools/vision.

Operability (для оркестратора и Prometheus)

GET /health

Liveness — всегда 200, тело { ok: true, status: "live", uptime_s }.

GET /ready

Readiness: пингует Postgres / Redis / LiteLLM. 200 если DB+Redis ok (LiteLLM down → status=degraded), 503 иначе.

GET /metrics

Prometheus exposition format. Метрики: aimost_requests_total, aimost_tokens_total, aimost_blend_downgrades_total, aimost_errors_total, aimost_cache_*, aimost_process_uptime_seconds.

Админ (требует role=admin)

Все под /api/v1/admin/*, JWT + role=admin.

  • GET/POST/PATCH/DELETE upstream-accounts — L2 direct провайдеры (зашифрованные api-ключи).
  • GET/POST/PATCH/DELETE self-hosted-nodes — L3 own-hw inference.
  • GET/PATCH model-routing — preferred_order и blend-таргеты.
  • GET users, PATCH users/:id — promote/demote.
  • GET cache/stats, DELETE cache/entries, DELETE cache/stats.
  • GET blend/shadow/stats, GET blend/shadow/sample/:id.
  • POST sync-pricing — pull OpenRouter каталог + наценка. Также вызывается cron'ом 6h.
  • GET audit — журнал действий админов (фильтр по ?action=...).