Баланс, расчёты и повторы

Гайды

Денежные значения передаются строками в рублях с 7 знаками после точки. GET /balance возвращает balance, reserved и available; доступный остаток учитывает резерв незавершённых запросов.

Резервирование отключено: деньги списываются по фактическому использованию. Отрицательный итоговый баланс допускается, но при любом отрицательном остатке новая генерация запрещена. При балансе меньше 100 ₽ допускается до трёх незавершённых запросов по всем операциям. Расход может включать несколько фактически оплаченных попыток. Ошибка сама по себе не означает бесплатную операцию: подтверждённое списание отражается в истории.

billing.charged — общий клиентский расход запроса; billing.refunded — учтённые возвраты. Поздний или частичный возврат появляется отдельной операцией по исходным условиям запроса. Повтор сверки не дублирует деньги.

billing.status=pending означает, что расчёт ещё уточняется. Неизвестная стоимость не превращается в установленный ноль. По запросу, завершившемуся ошибкой, также проверяйте финансовую историю.

GET /balance/transactions показывает собственные денежные операции. GET /requests и /usage — собственную историю. Чужие запросы и файлы возвращают 404.

Idempotency-Key: от 1 до 191 символа; разрешены латинские буквы, цифры, точка, дефис, подчёркивание и двоеточие. Область ключа — клиент. Повтор после очистки содержимого возвращает 410, сохраняя финансовую историю и идентичность операции.

cURL · GET /balance

bash

curl "https://formula-ai.ru/api/v1/balance" \
  -H "Authorization: Bearer $AI_SERVICE_API_KEY"

cURL · GET /balance/transactions?page=1

bash

curl "https://formula-ai.ru/api/v1/balance/transactions?page=1" \
  -H "Authorization: Bearer $AI_SERVICE_API_KEY"

PHP · GET /balance

<?php
$key = getenv("AI_SERVICE_API_KEY");
$url = "https://formula-ai.ru/api/v1/balance";
$handle = curl_init($url);
curl_setopt_array($handle, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . $key],
]);
if (getenv("AI_SERVICE_CA")) {
    curl_setopt($handle, CURLOPT_CAINFO, getenv("AI_SERVICE_CA"));
}
$body = curl_exec($handle);
if ($body === false) {
    throw new RuntimeException(curl_error($handle));
}
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
curl_close($handle);
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
echo json_encode(["status" => $status, "result" => $result], JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);

PHP · GET /balance/transactions?page=1

<?php
$key = getenv("AI_SERVICE_API_KEY");
$url = "https://formula-ai.ru/api/v1/balance/transactions?page=1";
$handle = curl_init($url);
curl_setopt_array($handle, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . $key],
]);
if (getenv("AI_SERVICE_CA")) {
    curl_setopt($handle, CURLOPT_CAINFO, getenv("AI_SERVICE_CA"));
}
$body = curl_exec($handle);
if ($body === false) {
    throw new RuntimeException(curl_error($handle));
}
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
curl_close($handle);
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
echo json_encode(["status" => $status, "result" => $result], JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);

Примеры cURL используют Bash. Задайте AI_SERVICE_API_KEY и AI_SERVICE_MODEL; модель выберите из /models. В PHP для опроса/файла задайте AI_SERVICE_REQUEST_ID/AI_SERVICE_MEDIA_ID, для правки — AI_SERVICE_SOURCE_URL. Для локального сертификата используйте доверенный CA через --cacert, для PHP — AI_SERVICE_CA. Проверку TLS сохраняйте включённой.