API-справочник
GET /balance: currency=RUB, balance — остаток, reserved — резерв ранее принятых операций, available — доступный остаток. Денежные значения — десятичные строки с 7 знаками. Новые операции выполняются без резерва, списание проводится по фактическому использованию; применяется математическое округление.
Отрицательный итог допускается, но новый запрос генерации при любом отрицательном остатке получает 402. При нуле генерация разрешена. При остатке ниже 100 ₽ суммарно разрешено до трёх незавершённых запросов; превышение даёт 429. Повтор с прежним Idempotency-Key возвращает уже принятый запрос.
GET /balance/transactions?page=1: data — собственные операции, page — номер страницы, 50 записей. Поля: id, type, amount, reserved_delta, balance_after, reserved_after, request_id, original_operation_id, created_at.
Баланс, история и уведомления доступны в личном кабинете: https://formula-ai.ru/settings/billing. Пополнение через Robokassa станет доступно после настройки магазина. До этого баланс может пополнить администратор. Возврат со страницы оплаты сам по себе не подтверждает зачисление; оно проводится по проверенному уведомлению Robokassa.
cURL · GET /balance
curl "https://formula-ai.ru/api/v1/balance" \
-H "Authorization: Bearer $AI_SERVICE_API_KEY"cURL · GET /balance/transactions?page=1
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);Схемы метода
Обязательные поля, типы, параметры и ответы описаны в OpenAPI 3.1. Полный машинный справочник
Показать JSON-схемы
{
"openapi": "3.1.1",
"info": {
"title": "Formula AI API",
"version": "1",
"description": "Методы нашего сервиса. Доступность модели и её параметров определяется опубликованным проверенным маршрутом. Suno: 23 музыкальные и вспомогательные операции, схемы и ограничения параметров. Streaming текста, изображений и аудио: SSE, сохранённые части и собственный расчёт."
},
"servers": [
{
"url": "https://formula-ai.ru/api/v1"
}
],
"security": [
{
"ClientKey": []
}
],
"paths": {
"/balance": {
"get": {
"operationId": "getBalance",
"summary": "Баланс клиента",
"responses": {
"200": {
"description": "Собственные данные клиента.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Balance"
}
}
}
},
"default": {
"description": "Ошибка доступа или параметров.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/balance/transactions": {
"get": {
"operationId": "listTransactions",
"summary": "Финансовая история",
"responses": {
"200": {
"description": "Собственные данные клиента.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Transactions"
}
}
}
},
"default": {
"description": "Ошибка доступа или параметров.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000000,
"default": 1
},
"description": "По 50 записей, от новых к старым."
}
]
}
}
},
"components": {
"securitySchemes": {
"ClientKey": {
"type": "http",
"scheme": "bearer",
"description": "API-ключ клиента Formula AI."
}
},
"schemas": {
"PublicId": {
"type": "string",
"pattern": "^[a-f0-9]{32}$"
},
"ErrorDetail": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
},
"type": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
}
},
"required": [
"message",
"code"
]
},
"Error": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail"
},
"request_id": {
"$ref": "#/components/schemas/PublicId"
}
},
"required": [
"error",
"request_id"
]
},
"Balance": {
"type": "object",
"properties": {
"currency": {
"const": "RUB"
},
"balance": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{7}$",
"description": "Рубли, точная десятичная строка с 7 знаками."
},
"reserved": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{7}$",
"description": "Рубли, точная десятичная строка с 7 знаками."
},
"available": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{7}$",
"description": "Рубли, точная десятичная строка с 7 знаками."
}
},
"required": [
"currency",
"balance",
"reserved",
"available"
]
},
"Transactions": {
"type": "object",
"properties": {
"data": {
"type": "array",
"maxItems": 50,
"items": {
"$ref": "#/components/schemas/Transaction"
}
},
"page": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
}
},
"required": [
"data",
"page"
]
},
"Transaction": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"integer"
],
"description": "Численный идентификатор. MySQL может вернуть его строкой."
},
"type": {
"enum": [
"manual_set",
"manual_add",
"manual_adjust",
"reserve",
"charge",
"refund",
"release"
]
},
"amount": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{7}$",
"description": "Рубли, точная десятичная строка с 7 знаками."
},
"reserved_delta": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{7}$",
"description": "Рубли, точная десятичная строка с 7 знаками."
},
"balance_after": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{7}$",
"description": "Рубли, точная десятичная строка с 7 знаками."
},
"reserved_after": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{7}$",
"description": "Рубли, точная десятичная строка с 7 знаками."
},
"request_id": {
"type": [
"string",
"null"
]
},
"original_operation_id": {
"type": [
"string",
"integer",
"null"
]
},
"created_at": {
"type": [
"string",
"null"
],
"description": "Время сервиса Europe/Moscow: YYYY-MM-DD HH:mm:ss, возможно дробная часть секунд."
}
},
"required": [
"id",
"type",
"amount",
"reserved_delta",
"balance_after",
"reserved_after",
"request_id",
"original_operation_id",
"created_at"
]
}
}
},
"externalDocs": {
"url": "https://formula-ai.ru/docs"
}
}Примеры 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 сохраняйте включённой.