API reference

Docs

OpenAI-совместимый API, фиксированная цена, прозрачный ledger. Базовый URL: https://api.example.com (локально — http://127.0.0.1:8000, текущая beta — https://sandy-shark-0509.a.tuna.free).

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

Три типа токенов:

Токен	Кто	Заголовок
`sk_...`	покупатель	`Authorization: Bearer sk_...`
`prov_...`	поставщик	`Authorization: Bearer prov_...`
admin token	админ	`X-Admin-Token: ...`

Для браузерной панели используйте POST /v1/auth/session — он ставит HttpOnly-cookie.

Пополнение

В production включите MARKET_PAYMENT_PROVIDER=yookassa или stripe. Для ЮKassa укажите shopId, секретный ключ и webhook:

https://api.example.com/v1/payments/yookassa/webhook

В локальном режиме доступен POST /v1/buyer/topup (mock) и POST /v1/payments/mock/intent + /confirm.

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

# 1. Регистрация покупателя
curl -s -X POST http://127.0.0.1:8000/v1/buyer/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'

# 2. Пополнение (local mock)
curl -s -X POST http://127.0.0.1:8000/v1/buyer/topup \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"amount_usd":5}'

# 3. Запрос
curl -s -X POST http://127.0.0.1:8000/v1/chat/completions \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"qwen2.5-0.5b",
    "messages":[{"role":"user","content":"Say hello"}],
    "max_tokens":32,
    "stream":false
  }'

Ключевые эндпоинты

Метод	Путь	Что делает
POST	`/v1/auth/session`	создать браузерную сессию по токену
GET	`/v1/auth/me`	текущая роль и субъект
POST	`/v1/auth/logout`	выйти
POST	`/v1/buyer/register`	регистрация покупателя
POST	`/v1/buyer/topup`	mock-пополнение
GET	`/v1/buyer/balance`	баланс
GET	`/v1/buyer/usage`	usage records
GET	`/v1/buyer/invoice`	инвойс
GET	`/v1/models`	публичный каталог и цены
POST	`/v1/chat/completions`	OpenAI-совместимый chat
POST	`/v1/seller/register`	регистрация поставщика
POST	`/v1/seller/offers`	создать/обновить оффер
GET	`/v1/seller/earnings`	payable / holdback
POST	`/v1/seller/payouts/request`	запросить выплату
GET	`/v1/admin/stats`	GMV, margin, counts
GET	`/v1/admin/ledger`	ledger entries
POST	`/v1/admin/healthcheck`	прогнать healthcheck

Ошибки

Код	HTTP	Когда
`price_ceiling_exceeded`	422	retail выше `max_price`
`max_cost_too_low`	422	`max_cost_usd` не покрывает даже input
`insufficient_balance`	402	не хватает баланса на reserve
`no_capacity`	503	нет healthy-провайдера
`rate_limit_exceeded`	429	превышен RPM
`idempotency_conflict`	422	тот же ключ с другим телом
`invalid_api_key`	401	ключ неверный или отозван

Streaming

При stream: true ответ идёт как SSE:

data: {"choices":[{"delta":{"content":"Hello"}}]}
data: {"choices":[{"delta":{"content":"!"}}]}
data: [DONE]

Брокер фиксирует первый содержательный чанк как точку commit: после него failover уже не делается.

Цена и биллинг

Retail фиксируется в PriceSnapshot до запроса.
Сначала резервируется верхняя граница, потом списывается фактический usage.
Wholesale поставщика — 80–90% retail; take rate платформы — 10–20%.
10% wholesale уходит в holdback на 14 дней.

Скачать OpenAPI JSON