Справочник API

Все эндпоинты партнёрского биллинг-API с параметрами.

billing

get/v1/billing/api-keys

Список API-ключей

Ключи партнёра: префикс, метка, активность, даты. Сырые ключи никогда не возвращаются.

Ответы

200 Список ключей
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

post/v1/billing/api-keys

Создать API-ключ

Создаёт новый ключ fl_live_… Сырое значение возвращается ровно один раз — сохраните его сразу.

Тело запроса

label

string

Произвольная метка (до 120 символов)

Ответы

201 Ключ создан; сырое значение — один раз
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

delete/v1/billing/api-keys/{id}

Отозвать API-ключ

Деактивирует ключ партнёра по его id. Идемпотентно: для чужого id совпадений нет, ошибка не возвращается. Можно отозвать и ключ, которым выполняется сам запрос.

Параметры (1)

id *

path · string

Идентификатор ключа

Ответы

200 Ключ деактивирован (или уже был)
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

get/v1/billing/balance

Баланс партнёра

Возвращает total (всего зачислено), used (подтверждённый lifetime-расход), reserved (в открытых резервах задач), available (доступно = total − used − reserved, не ниже 0) и флаг isLow. Суммы — в франках (₣), внутренней учётной единице платформы.

Ответы

200 Баланс получен
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

get/v1/billing/legal-invoices/{id}/pdf

PDF счёта

PDF-файл счёта (inline; иногда — редирект на файл банка). Лимит: 12 запросов/мин.

Параметры (1)

id *

path · string

Идентификатор счёта

Ответы

200 PDF-файл
302 Редирект на PDF-файл банка
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

post/v1/billing/legal-invoices/{id}/refresh

Обновить статус счёта

Запрашивает актуальный статус счёта у банка. Лимит: 6 запросов/мин.

Параметры (1)

id *

path · string

Идентификатор счёта

Ответы

200 Актуальный статус
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

post/v1/billing/legal-invoices/{id}/sbp-link

СБП B2B-ссылка

Создаёт QR-ссылку оплаты счёта через СБП B2B. Лимит: 6 запросов/мин.

Параметры (1)

id *

path · string

Идентификатор счёта

Ответы

200 Ссылка СБП
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

post/v1/billing/legal-invoices/create

Выставить счёт юрлицу

Создаёт счёт через T-Bank Business; при оплате баланс зачисляется автоматически (₽→₣ 1:1). Лимит: 3 запроса/мин.

Тело запроса

amountRub *	integer	Сумма счёта в рублях (1–100 000)
expectedProfileRevision *	integer	Ревизия профиля, под которую создаётся счёт (≥1; защита от реквизитов-призраков)
comment	string	Комментарий (до 140 символов)

Ответы

201 Счёт создан
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

get/v1/billing/legal-invoices/history

История счетов

Счета юрлица со статусами, суммами и датами зачисления.

Параметры (2)

page	query · integer	Номер страницы
limit	query · integer · ≤100	Размер страницы

Ответы

200 Список счетов
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

get/v1/billing/legal-invoices/profile

Реквизиты юрлица

Профиль компании для выставления счетов (ИНН, название, адрес и т.д.).

Ответы

200 Профиль
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

put/v1/billing/legal-invoices/profile

Сохранить реквизиты

Создаёт или обновляет профиль компании для счетов.

Тело запроса

companyName *	string	Название компании (2–512 символов)
inn *	string	ИНН — 10 или 12 цифр
email *	string	E-mail для счетов
kpp	string	КПП — 9 цифр (если есть)
phone	string	Телефон (до 32 символов)
expectedProfileRevision	integer	Оптимистичная блокировка: ожидаемая ревизия профиля (≥1)

Ответы

200 Профиль сохранён
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

get/v1/billing/payment/history

История пополнений

Список платёжных операций пополнения с их статусами (pending/authorized/confirmed/canceled/rejected/failed). Возвращает последние 50 операций.

Ответы

200 История пополнений
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

post/v1/billing/payment/link

Ссылка на пополнение

Создаёт платёжную ссылку T-Bank для пополнения баланса (₽→₣ 1:1). Заголовок Idempotency-Key обязателен: повтор с тем же ключом возвращает тот же платёж, а не создаёт новый. Сохранение карты не доступно программно. Ссылка открывается плательщиком в браузере. Лимит: 3 запроса/мин.

Параметры (1)

Idempotency-Key *

header · string

Ключ идемпотентности (до 128 символов; повтор с тем же ключом и той же суммой возвращает тот же платёж, иная сумма — 409)

Тело запроса

amountRub *	integer	Сумма в рублях (1–100 000); 1 ₽ = 1 ₣
description	string	Произвольное описание (до 140 символов)

Ответы

201 Платёж создан (или возвращён существующий): paymentUrl для оплаты
400 Нет/некорректный Idempotency-Key или сумма вне диапазона
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

get/v1/billing/pricing/catalog

Витрина цен

Базовая витрина цен по семействам (видео/изображения/аудио/текст/обработка) с единицами тарификации. Ответ не кэшируется (no-store); перечитывать достаточно раз в 24 часа (refreshAfterSeconds).

Ответы

200 Каталог цен
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

post/v1/billing/pricing/estimate

Оценка стоимости запуска

Оценка стоимости операции без побочных эффектов, по вашему тарифу (тот же механизм, что резервирует средства при запуске). Передайте модель и параметры; URL-медиа не нужно — только счётчики референсов.

Тело запроса

modelId *	string	Идентификатор модели (как в /studio/models)
duration	integer	Длительность видео, секунды (3–30)
operation	string	Тип операции: text_to_video, image_to_video, reference_to_video, first_last_frame, text_to_image, image_to_image, audio_generation, video_to_video
resolution	string	Разрешение (720p/1080p/4k — зависит от модели)
aspectRatio	string	Соотношение сторон
mode	string	Режим модели, если применим
executionMode	string	Маршрут исполнения (xai_api/supergrok/openai_api/openai_codex)
quality	string	Уровень качества (low/medium/high) для codex-маршрута gpt-image-2
prompt	string	Промпт (до 3000 символов; нужен для токен-цены google-моделей)
imageCount	integer	Число входных изображений (MIST i2i)
referenceImageCount	integer	Число референс-изображений (0–30)
referenceVideoCount	integer	Число референс-видео (0–10)
referenceAudioCount	integer	Число референс-аудио (0–10)

Ответы

200 Квота стоимости по действующему тарифу
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

get/v1/billing/tariff

Тарифный план

Действующий тариф (base/pro/max/ultra), назначенный и заработанный планы, lifetime-расход (₣), следующий уровень и сколько осталось до него, процент скидки от базовой цены.

Ответы

200 Тариф получен
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

get/v1/billing/transactions

История транзакций

Постраничный журнал операций: тип (topup/reservation/confirm/refund; debit — редкие легаси-строки), сумма ₣, цена за единицу, задача, дата, атрибуция. Пагинация page/limit (limit ≤ 100).

Параметры (6)

type	query · string · topup \| reservation \| confirm \| refund \| debit	Фильтр по типу транзакции (debit — легаси-строки)
attribution	query · string · all \| company \| personal	Чьи пополнения показывать: все / компании / личные
dateFrom	query · string	Начало периода (ISO 8601)
dateTo	query · string	Конец периода (ISO 8601)
page	query · integer	Номер страницы
limit	query · integer · ≤100	Размер страницы

Ответы

200 Список транзакций с пагинацией
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

get/v1/billing/transactions/export

Экспорт транзакций в CSV

Выгрузка журнала в CSV (attachment). Те же фильтры, что у списка; не более 10 000 строк за выгрузку — при превышении в конец добавляется строка-комментарий `# truncated: …` с полным количеством.

Параметры (5)

type	query · string · topup \| reservation \| confirm \| refund \| debit	Фильтр по типу транзакции (debit — легаси-строки)
dateFrom	query · string	Начало периода (ISO 8601)
dateTo	query · string	Конец периода (ISO 8601)
format	query · string · csv	Формат выгрузки; единственный вариант — csv
attribution	query · string · all \| company \| personal	Чьи пополнения включать: все / компании / личные

Ответы

200 CSV-файл
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

get/v1/billing/usage/daily

Расход по дням

Подтверждённый расход по дням UTC: confirm минус возвраты, не привязанные к задачам.

Параметры (2)

dateFrom	query · string	Начало периода (ISO 8601)
dateTo	query · string	Конец периода (ISO 8601)

Ответы

200 Агрегация по дням
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

webhooks

get/v1/webhooks/deliveries

История доставок

Последние 50 доставок партнёра со статусами (pending/delivering/delivered/uncertain/dead_lettered), попытками и кодами ответов.

Параметры (2)

endpointId	query · string	Фильтр по эндпоинту
status	query · string · pending \| delivering \| delivered \| uncertain \| dead_lettered	Фильтр по статусу доставки

Ответы

200 Список доставок
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

post/v1/webhooks/deliveries/{id}/replay

Повторить доставку

Ставит доставку (uncertain, dead_lettered или delivered) обратно в очередь с тем же eventId. Лимит: 30 запросов/мин.

Параметры (1)

id *

path · string

Идентификатор доставки

Ответы

200 Доставка пере-в-очереди
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

get/v1/webhooks/endpoints

Список вебхук-эндпоинтов

Эндпоинты партнёра: URL, подписки, активность. Секреты никогда не возвращаются.

Ответы

200 Список эндпоинтов
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

post/v1/webhooks/endpoints

Зарегистрировать эндпоинт

Создаёт эндпоинт; секрет whsec_… возвращается ровно один раз. URL — публичный HTTPS; внутренние адреса отклоняются. До 10 эндпоинтов на партнёра. Лимит: 10 запросов/мин.

Тело запроса

url *	string	Публичный HTTPS-URL получателя
eventTypes *	array	Типы событий (billing.settled, billing.refunded, billing.topup.confirmed, billing.low_balance, billing.invoice.status_changed, task.succeeded, task.failed, task.refunded, webhook.test)
description	string	Метка (до 140 символов)

Ответы

201 Эндпоинт создан; секрет — один раз
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

delete/v1/webhooks/endpoints/{id}

Удалить эндпоинт

Удаляет эндпоинт партнёра; его ожидающие доставки исчезают вместе с ним.

Параметры (1)

id *

path · string

Идентификатор эндпоинта

Ответы

200 Эндпоинт удалён
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

post/v1/webhooks/endpoints/{id}/rotate-secret

Ротация секрета

Генерирует новый подписывающий секрет; старый перестаёт работать немедленно. Новое значение — один раз. Периода перекрытия нет: доставки в полёте немедленно подписываются новым секретом. Лимит: 10 запросов/мин.

Параметры (1)

id *

path · string

Идентификатор эндпоинта

Ответы

200 Новый секрет
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

post/v1/webhooks/endpoints/{id}/test

Тестовое событие

Ставит в очередь событие webhook.test ровно для ЭТОГО эндпоинта — проверьте приём и подпись. Лимит: 6 запросов/мин.

Параметры (1)

id *

path · string

Идентификатор эндпоинта

Ответы

200 Событие поставлено в очередь
401 Ключ отсутствует или недействителен
403 Legacy service-ключи не принимаются: нужен партнёрский API-ключ
429 Превышен лимит запросов (по умолчанию 60/мин на партнёра); заголовок Retry-After даёт секунды до сброса окна

Для AI-агентов/docs/reference.md