Документация API

Доступные модели

Сценарии использования

Каждый ключ имеет лимит токенов. После исчерпания лимита нужен новый ключ, а списание идёт по фактическим prompt- и completion-токенам. Тарифы для Cursor / Claude Code дороже из-за другого характера нагрузки: IDE чаще отправляет длинный контекст проекта и генерирует более объёмные ответы.

Эндпоинты

API совместим с OpenAI Chat Completions. Используйте любой клиент для OpenAI (Cursor, n8n, OpenAI SDK, LangChain, Claude Code) — он будет работать «из коробки».

Legacy URL https://kupiapi.ru/api/v1/chat по-прежнему работает.

Публичный список моделей в OpenAI-формате ({ object: "list", data: [...] }). Если передан валидный ключ, у привязанной к нему модели будет default: true.

Streaming

Запрос с stream: true сейчас обрабатывается как обычный non-stream запрос: ответ возвращается целиком, а в заголовке отдаётся x-kupiapi-stream-fallback: non_stream. Это сделано для совместимости с клиентами, которые включают стриминг по умолчанию (Cursor, n8n, OpenAI SDK ≥ 1.x). В каждом ответе также есть x-kupiapi-stream-supported: false, чтобы клиенты могли надёжно детектировать поддержку реального SSE.

Полноценный SSE-стриминг — отдельный roadmap-пункт; до его релиза список выше остаётся стабильным контрактом.

Формат ошибок

Все ошибки возвращаются в OpenAI-совместимом формате с заголовкомx-request-id для сопоставления с логами поддержки.

{
  "error": {
    "message": "Баланс токенов по этому ключу закончился…",
    "type": "insufficient_quota",
    "code": "tokens_exhausted"
  }
}

Возможные type: invalid_request_error, insufficient_quota, api_error, rate_limit_error, server_error.

Получить список моделей

curl https://kupiapi.ru/v1/models

Авторизация необязательна. Передача Authorization: Bearer … добавляет default: true к модели купленного ключа.

Пополнение существующего ключа

Можно пополнить уже выпущенный ключ через тот же T-Bank без создания нового ключа. Сам ключ не меняется — увеличивается только баланс токенов. Коэффициент списания (billingMultiplier) остаётся таким, каким был в момент покупки или последнего ручного изменения.

1. Превью пополнения (без оплаты):

curl -X POST https://kupiapi.ru/api/keys/topup-preview \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"rk_live_…","amountRub":150}'

Возвращает providerName, tokens.remainingEffective, tokensToAdd, balanceAfterTopup. Полный ключ в ответе не возвращается — только keyPrefix.

2. Запуск платежа:

curl -X POST https://kupiapi.ru/api/checkout/topup \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"rk_live_…","amountRub":150}'

Возвращает paymentUrl — ссылку на T-Bank. После успешной оплаты webhook увеличит tokensPurchased у этого же ключа и запишет строку в BalanceTransaction с уникальным orderId: дубликат webhook не сможет начислить токены повторно.

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

Передайте API-ключ как Bearer-токен в заголовке Authorization.

Пример запроса

curl https://kupiapi.ru/v1/chat/completions \
  -H "Authorization: Bearer rk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Привет!"}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

Тело запроса

Пример ответа

{
  "id": "chatcmpl-abc123",
  "provider": "openai",
  "model": "gpt-5.4-mini",
  "content": "Привет! Чем могу помочь?",
  "finishReason": "stop",
  "usage": {
    "promptTokens": 9,
    "completionTokens": 12,
    "totalTokens": 21
  }
}

Ошибки