Документация разработчика

1. Быстрый старт

Шлюз говорит на двух протоколах сразу, поэтому менять в коде нужно всего два значения: базовый адрес и ключ. Какой адрес брать — зависит только от SDK, который вы уже используете:

• OpenAI SDK, cURL, Cursor IDE: http://localhost:3000/v1
• Anthropic SDK, Claude Code CLI: http://localhost:3000 — клиент Anthropic сам добавит /v1/messages, поэтому /v1 в адресе быть не должно.

Вариант A — одной командой

Скрипт пропишет переменные окружения за вас. macOS и Linux:

curl -fsSL http://localhost:3000/setup.sh | bash

Windows, PowerShell:

irm http://localhost:3000/setup.ps1 | iex

Скрипт под один клиент

Без параметров скрипт настраивает сразу всё. Если нужен один инструмент — добавьте ?app=: тогда в профиль попадут только те переменные, которые этот клиент действительно читает (например aider читает OPENAI_API_BASE, а не OPENAI_BASE_URL), и скрипт предупредит, если его CLI не установлен.

curl -fsSL http://localhost:3000/setup.sh?app=claude | bash   # Claude Code
curl -fsSL http://localhost:3000/setup.sh?app=codex  | bash   # Codex CLI
curl -fsSL http://localhost:3000/setup.sh?app=cursor | bash   # Cursor
curl -fsSL http://localhost:3000/setup.sh?app=aider  | bash   # aider
curl -fsSL http://localhost:3000/setup.sh?app=sdk    | bash   # SDK и свои скрипты

То же и для PowerShell: irm "http://localhost:3000/setup.ps1?app=claude" | iex. У каждого клиента свой помеченный блок (# >>> kabero gateway (claude) >>>), поэтому установки не затирают друг друга, а --uninstall с тем же ?app= убирает только его. Полный список переменных по каждому клиенту отдаёт GET /api/setup/apps.

Ключ скрипт спросит сам — так он не остаётся в истории команд. Если ключ нужно передать сразу (CI, Dockerfile), используйте переменную KABERO_API_KEY=sk-live-… или флаг: bash -s -- --key sk-live-….

Что скрипт делает:

1. Проверяет ключ запросом GET /api/user/me и показывает ваш текущий баланс — если ключ отозван, вы узнаете об этом сразу, а не из первой 401 в проекте.
2. Дописывает в ваш профиль (~/.zshrc, ~/.bashrc, ~/.bash_profile или ~/.config/fish/conf.d/kabero-gateway.fish) блок между метками # >>> kabero gateway >>> и # <<< kabero gateway <<<. Без ?app= это пять переменных: OPENAI_BASE_URL, OPENAI_API_KEY, ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN; с ?app= — только нужные выбранному клиенту.
3. Повторный запуск заменяет этот блок целиком, а не добавляет второй. Остальные строки профиля не трогаются.

Полезные флаги:

• --print — только вывести строки export …, ничего не записывая (удобно для .env или Dockerfile).
• --uninstall — удалить блок и вернуть профиль к исходному виду.
• --no-verify — не обращаться к шлюзу (например, при настройке на машине без доступа к сети).

curl -fsSL http://localhost:3000/setup.sh | bash -s -- --uninstall

Вариант B — вручную

Те же переменные, если вы предпочитаете прописать их сами или положить в .env:

export OPENAI_BASE_URL="http://localhost:3000/v1"
export OPENAI_API_KEY="sk-live-YOUR_API_KEY"

export ANTHROPIC_BASE_URL="http://localhost:3000"
export ANTHROPIC_API_KEY="sk-live-YOUR_API_KEY"
export ANTHROPIC_AUTH_TOKEN="sk-live-YOUR_API_KEY"

ANTHROPIC_API_KEY уходит в заголовке x-api-key, ANTHROPIC_AUTH_TOKEN — в Authorization: Bearer. Шлюз принимает оба, а разные версии Claude Code читают разные переменные, поэтому проще задать обе одним и тем же ключом.

Проверка, что всё работает

Один запрос без траты токенов — список доступных вам моделей:

curl -s http://localhost:3000/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | head -c 300

Пустой список или 401 означают, что переменные не подхватились: откройте новое окно терминала или выполните source ~/.zshrc. После первого платного запроса остаток баланса приходит в заголовке x-kabero-balance-usd — отдельный запрос для этого не нужен.

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

Доступ ко всем операциям шлюза осуществляется по единому API-ключу формата sk-live-….

Как получить ключ

1. Зарегистрируйтесь в личном кабинете на странице /dashboard (требуются только email и пароль).
2. Ваш первый API-ключ генерируется автоматически при создании аккаунта и отображается в разделе ключей.
3. При необходимости в личном кабинете можно создавать дополнительные ключи, отзывать скомпрометированные или ограничивать список доступных моделей для каждого ключа.

Передача ключа в запросах

Ключ передаётся в HTTP-заголовках одним из двух способов:

• Стандартный заголовок авторизации: Authorization: Bearer sk-live-YOUR_KEY
• Альтернативный заголовок (используется Anthropic SDK): x-api-key: sk-live-YOUR_KEY

Восстановление доступа

Сервис не использует отправку писем на email. При регистрации аккаунту присваивается одноразовый код восстановления, который отображается единственный раз. Сохраните его для сброса пароля; перевыпустить код можно в настройках кабинета, указав текущий пароль.

3. Эндпоинты шлюза

POST /v1/chat/completions

Основной эндпоинт генерации текста, полностью совместимый со спецификацией OpenAI Chat Completions. Поддерживает как синхронный ответ (JSON), так и потоковую передачу (Server-Sent Events).

Параметры тела запроса (JSON):

• model (string, обязательно) — идентификатор модели из каталога (например, gpt-4o, claude-sonnet-5, deepseek-chat).
• messages (array, обязательно) — массив сообщений диалога с полями role (system, user, assistant) и content.
• stream (boolean, опционально) — при значении true шлюз возвращает поток чанков text/event-stream.
• max_tokens / max_completion_tokens (integer, опционально) — ограничение длины ответа в токенах.
• temperature, top_p, stop — стандартные параметры управления генерацией.

GET /v1/models

Возвращает актуальный перечень доступных моделей в формате списка OpenAI. Если передан заголовок с API-ключом, возвращаются только модели, разрешённые для данного ключа. Без заголовка возвращается полный открытый каталог.

Каждая модель в ответе содержит расширенный блок тарификации за 1 миллион токенов:

{
  "id": "claude-sonnet-5",
  "object": "model",
  "display_name": "Claude 3.5 Sonnet",
  "context_length": 200000,
  "max_output_tokens": 8192,
  "pricing": {
    "input": 0.82,
    "output": 4.10,
    "cached_input": 0.082
  }
}

POST /v1/messages

Нативный эндпоинт формата Anthropic API. Позволяет инструментам экосистемы Claude (включая Claude Code CLI и библиотеки @anthropic-ai/sdk) работать напрямую со шлюзом без адаптеров.

Шлюз выполняет автоматическую трансляцию формата, сохраняя точность тарификации за фактически обработанные токены. Имена моделей (например, claude-3-7-sonnet-20250219 или claude-sonnet-latest) автоматически сопоставляются с соответствующими позициями каталога.

GET /setup.sh и GET /setup.ps1

Генераторы скрипта настройки окружения для POSIX-шеллов и для PowerShell. Ключ можно передать параметром (GET /setup.sh?key=sk-live-…) — тогда он уже вшит в скрипт; без параметра скрипт спросит ключ при запуске. Параметр проверяется на формат выдаваемых нами ключей, любое другое значение получает 400 вместо скрипта. Параметр app (all, claude, codex, cursor, aider, sdk) сужает скрипт до одного клиента; неизвестное значение настраивает всё.

GET /api/setup/apps

Список клиентов, которые понимает установщик, и переменные каждого — с уже подставленными адресами шлюза. Этот же ответ использует кабинет, поэтому список в интерфейсе не расходится с тем, что пишет скрипт.

Скрипт идемпотентен: он управляет одним помеченным блоком в профиле пользователя, поддерживает --print, --uninstall, --key, --no-verify и проверяет ключ перед записью. Подробности — в разделе Быстрый старт.

4. Примеры интеграции

cURL — OpenAI Chat Completions (JSON)

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-live-YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Привет! Напиши краткое приветствие."}
    ]
  }'

cURL — Потоковый ответ (Streaming SSE)

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-live-YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Посчитай от 1 до 5 через запятую."}
    ],
    "stream": true
  }'

cURL — Anthropic Messages (/v1/messages)

curl http://localhost:3000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-live-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Привет! Ответь одним словом."}
    ]
  }'

Python — OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3000/v1",
    api_key="sk-live-YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": "Ты полезный ассистент."},
        {"role": "user", "content": "Объясни закон Ома в двух предложениях."}
    ]
)

print(response.choices[0].message.content)

Node.js — OpenAI SDK

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:3000/v1',
  apiKey: 'sk-live-YOUR_API_KEY'
});

const completion = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Привет из Node.js!' }]
});

console.log(completion.choices[0].message.content);

Python — Anthropic SDK

import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:3000",
    api_key="sk-live-YOUR_API_KEY"
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Привет, Claude!"}]
)

print(message.content[0].text)

5. Тарификация и предоплаченный баланс

Сервис работает по системе предоплаты (Prepaid Credit). Вы пополняете баланс в долларах США (USDT) и расходуете средства исключительно на фактически обработанные запросы.

• Тарификация за токены: Стоимость рассчитывается отдельно за токены запроса (input), токены ответа (output) и кешированные токены (cached_input). Базовые ставки указаны за 1 миллион токенов (1M).
• Целочисленный учёт: В базе данных баланс хранится в микро-долларах (1 USD = 1 000 000 µUSD), что исключает погрешности округления при поштучных списаниях за токены.
• Минимальный чек за запрос: Для каждого успешно обслуженного запроса действует минимальный порог списания — 50 µUSD ($0.00005). Если объём токенов дешёвой модели даёт сумму меньше $0.00005, со счёта удерживается этот минимум. Запросы, завершившиеся с 0 токенов (ошибки валидации или отклонённые шлюзом), не тарифицируются ($0.00).
• Контроль достаточности средств (Admission Control): Перед отправкой запроса шлюз оценивает его максимальную потенциальную стоимость (токены промпта + ожидаемый объём ответа). Если текущий баланс меньше расчётной оценки, шлюз отклоняет запрос с ошибкой 402 Payment Required до отправки запроса моделям.
• Контроль остатка в заголовках ответа: Каждый обслуженный запрос возвращает заголовок x-kabero-balance-usd — остаток баланса уже с учётом списания за этот запрос (для потоковых ответов — остаток на момент начала генерации, так как заголовки уходят раньше тарификации). Когда остаток падает ниже $1.00, добавляются x-kabero-balance-low: 1 и человекочитаемый x-kabero-warning. Те же заголовки есть и у ответа 402. Все три включены в Access-Control-Expose-Headers, поэтому читаются и из браузера.
• Защита от овердрафта при стриминге: В процессе потоковой отдачи токенов шлюз в реальном времени отслеживает накопленный расход. Если генерация превышает остаток баланса более чем на допустимый запас овердрафта ($0.02), поток корректно останавливается с сообщением [Остановлено: на балансе закончились средства], а с аккаунта списывается точная сумма за сгенерированные до остановки токены.

6. Коды ошибок шлюза

Шлюз возвращает стандартные HTTP-коды состояния и структурированные тела ошибок в формате OpenAI или Anthropic:

7. Лимиты и параллелизм

Шлюз спроектирован для интенсивной разработческой нагрузки (IDE, тесты, параллельные вызовы агентов):

• Параллельные запросы (Concurrency): На каждый API-ключ установлен лимит в 8 одновременных активных запросов (MAX_CONCURRENT_PER_KEY = 8). Это защищает ваш баланс от неконтролируемых утечек при сбоях клиентских циклов. При превышении порога возвращается 429 concurrency_limit.
• Частота запросов (RPM): Прокси-трафик к /v1/* не ограничивается искусственными минутными лимитами по IP-адресу. Вы можете генерировать частые серийные запросы, пока не исчерпан лимит одновременных соединений.
• Веб-интерфейс: Служебные эндпоинты авторизации и кабинета защищены лимитом 60 запросов в минуту на IP (авторизация — 10 запросов в минуту).