Баланс и списания
Баланс, резервы, транзакции, тарифы и оценка стоимости по API.
Все суммы — в франках (₣): внутренней учётной единице платформы (1₣ = 1 ₽ при расчётном курсе). Франк — не валюта и не платёжный инструмент.
Сначала зарегистрируйтесь в Apergrex
Для работы с API нужен личный кабинет Apergrex: зарегистрируйтесь, затем создайте API-ключ своего аккаунта.
Зарегистрироваться на Apergrex
Открыть кабинет и получить API-ключ
Два способа пополнить один баланс
| Через личный кабинет | Через API |
|---|---|
| Откройте раздел «Баланс», выберите способ и сумму пополнения, завершите оплату. | Вызовите POST /v1/billing/payment/link с API-ключом, получите платёжную ссылку и завершите оплату по ней. |
| Подходит для ручного пополнения и просмотра истории. | Подходит для встраивания пополнения в свою интеграцию. |
API-ключ определяет аккаунт, с баланса которого оплачиваются операции. Для ключа того же аккаунта кабинет и API используют один баланс: после успешного пополнения средства доступны для API-операций, а резерв и списание выполняются автоматически при запуске и завершении задачи.
Оплата через API не заменяет регистрацию и не создаёт отдельный баланс. Сам запрос платёжной ссылки не пополняет счёт: дождитесь успешной оплаты и проверьте GET /v1/billing/balance. Если у вас несколько аккаунтов или рабочих пространств, проверьте, какому из них принадлежит ключ.
Как устроен цикл списания
- Резерв (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: … с полным количеством.
Пополнение
POST /v1/billing/payment/link с обязательным заголовком Idempotency-Key (до 128 символов) создаёт ссылку на оплату картой через T-Bank. Повторный вызов с тем же ключом возвращает ту же ссылку, пока платёж не завершён отказом — новый заказ у банка не создаётся.
Фискальный чек (54-ФЗ) формируется автоматически на email аккаунта партнёра, от имени которого выпущен API-ключ, и уходит в платёжный терминал вместе с запросом Init — отдельно передавать адрес плательщика не нужно и нельзя.
Тарифы
Тарифный уровень применяется автоматически по накопленному расходу (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 не нужны, они появляются только при запуске.