Биллинг
Баланс, резервы, транзакции, тарифы и оценка стоимости по API.
Биллинг
Все суммы — в франках (₣): внутренней учётной единице платформы (1₣ = 1 ₽ при расчётном курсе). Франк — не валюта и не платёжный инструмент.
Как устроен цикл списания
- Резерв (hold) — при запуске операции стоимость резервируется на балансе (
reserved). - Выполнение — задача выполняется у провайдера.
- Списание (confirm) — по факту списывается реальное потребление; если провайдер вернул меньше — излишек резерва автоматически возвращается.
- Возврат (refund) — при ошибке резерв возвращается полностью.
Типы транзакций в журнале: topup (пополнение), reservation, confirm, refund; debit — редкие легаси-строки.
Эндпоинты
| Что | Эндпоинт |
|---|---|
| Баланс | GET /v1/billing/balance |
| Тарифный план | GET /v1/billing/tariff |
| Транзакции | GET /v1/billing/transactions |
| Выписка CSV | GET /v1/billing/transactions/export?format=csv |
| Расход по дням | GET /v1/billing/usage/daily |
| Витрина цен | GET /v1/billing/pricing/catalog |
| Оценка стоимости | POST /v1/billing/pricing/estimate |
| Пополнение (ссылка на оплату) | POST /v1/billing/payment/link (Idempotency-Key) |
| История пополнений | GET /v1/billing/payment/history |
| Счета юрлицам | POST/GET /v1/billing/legal-invoices/* |
Транзакции
Постраничный журнал с фильтрами:
curl -H "X-API-Key: $FRANKLAB_KEY" \
"https://apergrex.ru/franklab/api/v1/billing/transactions?type=confirm&page=1&limit=50"
Параметры: type (topup/reservation/confirm/refund/debit), attribution (all/company/personal — чьи пополнения включать), dateFrom/dateTo (ISO 8601), page (≥1), limit (1–100, по умолчанию 20). CSV-выгрузка принимает те же фильтры и отдаёт до 10 000 строк; при превышении — последняя строка-комментарий # truncated: … с полным количеством.
Тарифы
Тарифный уровень применяется автоматически по накопленному расходу (lifetime-спенд):
| Уровень | Скидка от базовой цены | Порог |
|---|---|---|
| BASE | — | — |
| PRO | 12.5% | > 5 000 ₣ |
| MAX | 25% | > 15 000 ₣ |
| ULTRA | 35% | > 50 000 ₣ |
Достигнутый уровень не понижается. Текущий план и прогресс до следующего уровня — GET /v1/billing/tariff; точная цена под вашим тарифом — POST /v1/billing/pricing/estimate.
Оценка стоимости
Оценка учитывает ваш тариф, параметры модели и промо-окна. Никаких побочных эффектов: оценка не резервирует средства и не создаёт задач.
curl -X POST -H "X-API-Key: $FRANKLAB_KEY" -H "Content-Type: application/json" \
-d '{"modelId":"mars-v1-5","duration":5,"resolution":"720p","operation":"text_to_video"}' \
https://apergrex.ru/franklab/api/v1/billing/pricing/estimate
Для моделей с референсами передавайте счётчики (referenceImageCount и т.п.) — сами URL не нужны, они появляются только при запуске.