Оплата

Цены в долларах, резервирование, списание, пределы и ledger.

Цены и баланс указаны в долларах США. estimatedCost, cost, available, held и total возвращаются десятичными строками без знака валюты. Для учета используйте decimal, а не float.

API

{
  "available": "128.42",
  "held": "0.36",
  "total": "128.78"
}

Промосредства и кредитный лимит

GET /api/v1/chat/credit может возвращать необязательный объект funding с разбивкой на предоплату, промосредства и одобренный кредит. Отсутствие объекта в старом ответе не означает нулевой остаток. Используйте client.getBalance() или spicyapi balance --json. Суммы передаются точными десятичными строками в USD, даты — в формате RFC3339.

prepaidAvailableUsd — доступная предоплата; grantAvailableUsd — сумма действующих промоначислений. Для каждой записи grants указаны availableUsd, heldUsd, spentUsd, status, startsAt, expiresAt и modelSlugs. Пустой список моделей означает все модели. Средства действуют только в свой срок и для разрешённых моделей; вывести их нельзя. Список содержит не более 100 начислений: сначала с остатком или зарезервированными средствами, затем внутри каждой группы — от новых к старым. grantsHasMore указывает на дополнительные записи: сумма видимого списка не заменяет общий итог.

credit.limitUsd — одобренный потолок, а не деньги на счёте. credit.availableUsd — неиспользованный кредит, usedUsd — начисленная непогашенная задолженность, heldUsd — резерв под принятые задачи. Истечение срока, отключение и превышение лимита ограничивают новые вызовы, но не списывают долг. available может стать отрицательным при использовании кредита: не отклоняйте запрос только по этому признаку. Положительный cashShortfallUsd означает нехватку средств после возврата внешнего платежа; промосредства и кредит её не покрывают. Допуск проверяет сервер.

Скидка определяет цену, а промосредства и кредит — источник оплаты. Освобождённый резерв возвращается к исходному источнику, не возобновляя истёкшее или отозванное начисление. Изменения вступают в силу после ручного одобрения. Обратитесь в поддержку: публичный API не позволяет увеличить собственный баланс. В журнале grant_expire означает истечение срока, grant_revoke — отзыв.

Использование текущего API-ключа

GET /api/v1/usage учитывает только задачи API-ключа, которым выполнена аутентификация. from и to — даты UTC в формате YYYY-MM-DD. Интервал [from,to) включает начало и исключает конец; максимум — 92 дня. По умолчанию to — завтрашняя дата UTC, а from — дата за семь дней до to. totalSpend и значения spend возвращаются десятичными строками в USD и включают только фактически списанные суммы по завершённым расчётам, без незакрытых резервов. Задачи относятся к дате создания, поэтому поздний расчёт может изменить расходы за предыдущий день. Ответ не показывает баланс счёта или остаток бюджета ключа.

Персональные скидки и акции

Предложение может действовать для всех пользователей или одного аккаунта, на все модели либо на выбранные. Постоянная скидка действует до отключения, ограниченная по времени — между фактическими датами начала и окончания. Персональные цены доступны только при входе в соответствующий аккаунт или расчёте с его API-ключом.

Скидки не суммируются: автоматически выбирается самая низкая доступная цена. Если обычная стоимость $10, общая скидка 10%, а персональная — 20%, цена составит $8. После завершения акции новые расчёты учитывают лучшую оставшуюся скидку либо обычную цену.

Обратный отсчёт не фиксирует цену. Запрашивайте jobs/quote с авторизацией и полными входными параметрами; при изменении акции, цены или параметров получите новый расчёт. Принятая задача сохраняет зафиксированную цену, даже если акция завершится во время выполнения. Итоговое списание не превышает зарезервированную сумму.

Скидки автоматически применяются к стоимости API-запросов, а не к сумме пополнения; это не кешбэк за пополнение. Дневной или месячный бюджет рассчитан по текущей цене. Акция может закончиться раньше бюджетного периода, поэтому учитывайте дату её окончания.

Единицы оплаты

pricing[].unit модели имеет значение per_image, per_second, per_request или per_1k_tokens. Читайте quantityField и pricing[].variant из каталога, не угадывайте поля input.

Hold, settle и release

createTask резервирует estimatedCost. succeeded списывается по фактическому использованию; failed, expired и исторические записи canceled освобождают всю сумму. Новую принятую задачу отменить нельзя. Задача и резерв создаются одной транзакцией, а расчет каждой задачи завершается ровно один раз.

Баланс и пределы

GET /api/v1/chat/credit возвращает available, held и total. Недостаток средств — 40201; дневной, месячный и общий пределы ключа, а также дневной предел платформы — 40202. Дневные пределы обновляются в полночь UTC, месячные — 1-го числа в полночь UTC, а общий предел не сбрасывается никогда. Явно заданный 0 означает без ограничений.

Леджер

Ledger работает append-only и отдельно хранит topup, bonus, hold, settle, refund, adjust и chargeback. Эти движения баланса не удаляются вместе с содержимым задач и остаются в истории расчетов.

Полные определения полей приведены в контракте OpenAPI 3.1.