API v1

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

REST API для доступа к 50+ AI-моделям. SSE-стриминг, per-token биллинг, JWT авторизация.

Getting Started

Base URL для всех запросов:

url
https://stone-ai-production.up.railway.app

Все запросы используют JSON. Ответы чата — Server-Sent Events (SSE). Авторизация через JWT токен в заголовке Authorization: Bearer <token>.

Быстрый старт:

  1. Зарегистрируйтесь: POST /api/auth/register
  2. Получите JWT токен из ответа
  3. Отправьте сообщение: POST /api/chat

Авторизация

Регистрация нового пользователя:

curl
curl -X POST https://stone-ai-production.up.railway.app/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "mypassword"}'

Ответ содержит JWT токен:

json
{
  "status": "ok",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 42,
    "email": "user@example.com",
    "balance_usd": 0.0
  }
}

Логин:

curl
curl -X POST https://stone-ai-production.up.railway.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "mypassword"}'

Также поддерживается OAuth: POST /api/auth/google и POST /api/auth/yandex.

POST /api/chat

Стриминг ответа от AI-модели через SSE.

ПараметрТипОписание
model_idstringID модели (см. /api/models). По умолчанию: gpt-4o-mini
messagesarrayМассив сообщений [{role, content}]
system_promptstring?Системный промпт (только для платных пользователей)

Пример с curl:

curl
curl -N -X POST https://stone-ai-production.up.railway.app/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "model_id": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Привет! Что такое AI?"}
    ]
  }'

Пример на Python:

python
import httpx

token = "YOUR_JWT_TOKEN"
url = "https://stone-ai-production.up.railway.app/api/chat"

with httpx.stream("POST", url,
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "model_id": "claude-haiku-4.5",
        "messages": [{"role": "user", "content": "Напиши хайку про AI"}]
    }
) as response:
    for line in response.iter_lines():
        if line.startswith("data: ") and line != "data: [DONE]":
            print(line[6:])

SSE-ответ содержит чанки контента, затем usage и billing:

json
data: {"choices": [{"delta": {"content": "Привет"}}]}
data: {"choices": [{"delta": {"content": "! AI — это..."}}]}
data: {"usage": {"tokens_in": 15, "tokens_out": 82}}
data: {"billing": {"tokens_in": 15, "tokens_out": 82, "cost_usd": 0.0003, "balance_usd": 9.99, "billing_mode": "per_token"}}
data: [DONE]

GET /api/models

Список всех доступных моделей с метаданными и ценами.

curl
curl https://stone-ai-production.up.railway.app/api/models
# Фильтры:
curl "https://stone-ai-production.up.railway.app/api/models?tier=lite"        # только бесплатные
curl "https://stone-ai-production.up.railway.app/api/models?company=OpenAI"   # по провайдеру
curl "https://stone-ai-production.up.railway.app/api/models?category=image"   # по категории

Ответ:

json
{
  "models": [
    {
      "id": "gpt-4o-mini",
      "name": "GPT-4o mini",
      "company": "OpenAI",
      "tier": "lite",
      "category": "chat",
      "price_weighted": 2.50,
      "price_input": 0.90,
      "price_output": 3.60,
      "context_length": "128K"
    },
    ...
  ]
}
ФильтрЗначенияОписание
tierlite | premiumlite = бесплатные (5 моделей), premium = платные
companyOpenAI, Anthropic, Google...15 провайдеров
categorychat | image | reason | search | codeТип модели

POST /api/chat/upload

Загрузка файлов (изображения, PDF) для использования в чате.

curl
curl -X POST https://stone-ai-production.up.railway.app/api/chat/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf"

Ответ:

json
{
  "file_id": "a1b2c3d4",
  "file_name": "document.pdf",
  "file_type": "pdf",
  "mime_type": "application/pdf",
  "size": 245000,
  "content": "Извлечённый текст из PDF..."
}

Для изображений content — base64 data URL. Для PDF — извлечённый текст. Максимум 10MB.

Биллинг

Stone AI использует per-token биллинг. Стоимость зависит от модели и количества токенов.

Формула: cost = (tokens_in × price_input + tokens_out × price_output) / 1,000,000

МодельInput $/1MOutput $/1MСредневзвешенная
gpt-4o-mini$0.90$3.60$2.50 (FREE)
claude-haiku-4.5$3.20$16.00$11.00 (FREE)
gpt-5.1$4.90$39.20$26.00
claude-opus-4$37.50$187.50$130.00
gemini-2.5-pro$5.00$40.00$26.00
flux-schnell——$0.012/img

5 моделей бесплатно (15 запросов/день). Остальные — per-token с баланса в USD.

Списание происходит ПОСЛЕ получения ответа, по реально использованным токенам.

Лимиты

ТарифLite моделиPremium модели
Free15/деньПо балансу (per-token)
Per-tokenБезлимит (с баланса)Безлимит (с баланса)
ПараметрЗначение
MAX_TOKENS_LITE4096 (макс. output для бесплатных)
MAX_TOKENS_PAID8192 (макс. output для платных)
Max file upload10MB
Rate limitНет жёсткого rate limit, лимитируется балансом

Коды ошибок

КодОписаниеРешение
401Unauthorized — невалидный или отсутствующий токенПроверьте Authorization header
402Payment Required — недостаточно средств для premium моделиПополните баланс на /topup
429Too Many Requests — лимит бесплатных запросов исчерпанПодождите до завтра или пополните баланс
400Bad Request — неверные параметрыПроверьте model_id и messages
503Service Unavailable — сервис оплаты временно недоступенПопробуйте позже

Ошибки возвращаются в формате:

json
{
  "detail": {
    "error": "Недостаточно средств. Баланс $0.01, примерная стоимость $0.26",
    "plan": "free",
    "tier": "premium",
    "used_today": 0,
    "limit": 0,
    "need_balance": true
  }
}