API-справочник
Перед генерацией можно отправить operation и input — обычное тело выбранной операции. Запрос требует клиентский Bearer, не создаёт задачу, не резервирует баланс и не обращается к платному методу поставщика.
Необязательный estimated_usage содержит целые количества по названиям тарифов, например prompt и completion. Без него текст приблизительно оценивается по числу символов и сообщений; max_tokens задаёт предел оцениваемого выхода. Изображения, инструменты и неизвестные единицы требуют подтверждённого количества.
status=estimated возвращает minimum и maximum в рублях с применённой наценкой. Это приблизительные значения, а не гарантия итоговой цены. Фактический расход может включать несколько оплаченных попыток fallback.
status=unknown возвращает null в обеих суммах и missing с недостающими данными. Неизвестная цена не выдаётся за нулевую. Используются только сохранённые тарифы и подтверждённый рублёвый курс.
cURL · POST /estimate
curl "https://formula-ai.ru/api/v1/estimate" \
-H "Authorization: Bearer $AI_SERVICE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: example-estimate-1" \
--data-binary "{
\"operation\": \"chat\",
\"input\": {
\"model\": \"$AI_SERVICE_MODEL\",
\"messages\": [
{
\"role\": \"user\",
\"content\": \"Reply OK\"
}
],
\"max_tokens\": 64
}
}"PHP · POST /estimate
<?php
$key = getenv("AI_SERVICE_API_KEY");
$url = "https://formula-ai.ru/api/v1/estimate";
$handle = curl_init($url);
curl_setopt_array($handle, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(["operation" => "chat", "input" => ["model" => getenv("AI_SERVICE_MODEL"), "messages" => [["role" => "user", "content" => "Reply OK"]], "max_tokens" => 64]], JSON_THROW_ON_ERROR),
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . $key, "Content-Type: application/json", "Idempotency-Key: php-estimate-1"],
]);
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": {
"/estimate": {
"post": {
"operationId": "estimateCost",
"summary": "Предварительная оценка без генерации и списания",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CostEstimateInput"
}
}
}
},
"responses": {
"200": {
"description": "Приблизительная оценка либо неизвестная стоимость.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CostEstimate"
}
}
}
},
"default": {
"description": "Ошибка доступа или параметров.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"ClientKey": {
"type": "http",
"scheme": "bearer",
"description": "API-ключ клиента Formula AI."
}
},
"schemas": {
"PublicId": {
"type": "string",
"pattern": "^[a-f0-9]{32}$"
},
"CostEstimateInput": {
"type": "object",
"properties": {
"operation": {
"type": "string"
},
"input": {
"type": "object",
"description": "Обычное тело выбранной операции с публичным model."
},
"estimated_usage": {
"type": "object",
"additionalProperties": {
"type": "integer",
"minimum": 0
},
"description": "Необязательные количества по названиям тарифов: prompt, completion и другие опубликованные единицы."
}
},
"required": [
"operation",
"input"
]
},
"CostEstimate": {
"type": "object",
"properties": {
"object": {
"const": "ai_service.cost_estimate"
},
"model": {
"type": "string"
},
"operation": {
"type": "string"
},
"currency": {
"const": "RUB"
},
"status": {
"enum": [
"estimated",
"unknown"
]
},
"minimum": {
"type": [
"string",
"null"
],
"pattern": "^[0-9]+\\.[0-9]{7}$"
},
"maximum": {
"type": [
"string",
"null"
],
"pattern": "^[0-9]+\\.[0-9]{7}$"
},
"estimated_usage": {
"type": "object",
"additionalProperties": {
"type": "integer",
"minimum": 0
}
},
"assumptions": {
"type": "array",
"items": {
"type": "string"
}
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"object",
"model",
"operation",
"currency",
"status",
"minimum",
"maximum",
"estimated_usage",
"assumptions",
"missing"
]
},
"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"
]
}
}
},
"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 сохраняйте включённой.