API-справочник
POST /embeddings принимает model и input: строку, массив строк, массив неотрицательных целых токенов или массив таких последовательностей. encoding_format=float либо base64. Необязательные dimensions, user и input_type зависят от модели; input_type: search_query, search_document, classification, clustering. Результат содержит data с векторами в формате модели, usage и ai_service с собственным расчётом.
POST /rerank принимает model, query и documents — массив строк. Необязательные top_n и return_documents управляют числом результатов и возвратом текстов. results содержит index и relevance_score.
POST /decisions принимает model, state и questions. state — строка, объект или массив контекста. questions — карта имён с type и instructions; noul возвращает вероятность, choice выбирает из criteria, score оценивает 2–10 уровней criteria. Ответы сохраняют имена вопросов в answers.
Операции выполняются через тот же баланс, идемпотентность, очередь и историю. Опубликованный маршрут нужен для конкретной модели; импорт схемы не подтверждает реальную интеграцию. HTTP 202 требует опроса /requests/{id}.
cURL · POST /embeddings
curl "https://formula-ai.ru/api/v1/embeddings" \
-H "Authorization: Bearer $AI_SERVICE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: example-embeddings-1" \
--data-binary "{
\"model\": \"$AI_SERVICE_MODEL\",
\"input\": [
\"A short text\",
\"Another text\"
],
\"encoding_format\": \"float\"
}"cURL · POST /rerank
curl "https://formula-ai.ru/api/v1/rerank" \
-H "Authorization: Bearer $AI_SERVICE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: example-rerank-1" \
--data-binary "{
\"model\": \"$AI_SERVICE_MODEL\",
\"query\": \"A useful guide\",
\"documents\": [
\"A guide to integration\",
\"A weather report\"
],
\"top_n\": 1
}"cURL · POST /decisions
curl "https://formula-ai.ru/api/v1/decisions" \
-H "Authorization: Bearer $AI_SERVICE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: example-decisions-1" \
--data-binary "{
\"model\": \"$AI_SERVICE_MODEL\",
\"state\": \"Please send an integration guide\",
\"questions\": {
\"needs_guide\": {
\"type\": \"noul\",
\"instructions\": \"Does the message request a guide?\"
}
}
}"PHP · POST /embeddings
<?php
$key = getenv("AI_SERVICE_API_KEY");
$url = "https://formula-ai.ru/api/v1/embeddings";
$handle = curl_init($url);
curl_setopt_array($handle, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(["model" => getenv("AI_SERVICE_MODEL"), "input" => ["A short text", "Another text"], "encoding_format" => "float"], JSON_THROW_ON_ERROR),
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . $key, "Content-Type: application/json", "Idempotency-Key: php-embeddings-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);PHP · POST /rerank
<?php
$key = getenv("AI_SERVICE_API_KEY");
$url = "https://formula-ai.ru/api/v1/rerank";
$handle = curl_init($url);
curl_setopt_array($handle, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(["model" => getenv("AI_SERVICE_MODEL"), "query" => "A useful guide", "documents" => ["A guide to integration", "A weather report"], "top_n" => 1], JSON_THROW_ON_ERROR),
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . $key, "Content-Type: application/json", "Idempotency-Key: php-rerank-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);PHP · POST /decisions
<?php
$key = getenv("AI_SERVICE_API_KEY");
$url = "https://formula-ai.ru/api/v1/decisions";
$handle = curl_init($url);
curl_setopt_array($handle, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(["model" => getenv("AI_SERVICE_MODEL"), "state" => "Please send an integration guide", "questions" => ["needs_guide" => ["type" => "noul", "instructions" => "Does the message request a guide?"]]], JSON_THROW_ON_ERROR),
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . $key, "Content-Type: application/json", "Idempotency-Key: php-decisions-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": {
"/embeddings": {
"post": {
"operationId": "createEmbeddings",
"summary": "Эмбеддинги текста",
"description": "JSON-объект. Действуют ограничения выбранной модели и серверного окружения. Параметры допускаются только совместимым проверенным маршрутом; неподдержанные поля не отбрасываются. Повтор с прежним Idempotency-Key возвращает существующую операцию. После очистки её содержимого возвращается 410.",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 191,
"pattern": "^[A-Za-z0-9._:\\-]+$"
},
"description": "Область ключа — клиент. Изменение параметров с прежним ключом даёт 409."
},
{
"name": "Prefer",
"in": "header",
"schema": {
"type": "string"
},
"description": "respond-async: вернуть собственный ID без ожидания поставщика, в том числе при stream=true. Формат тела и Idempotency-Key сохраняются. Готовый повтор возвращает сохранённый результат."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmbeddingInput"
}
}
}
},
"responses": {
"200": {
"description": "Готовый результат и клиентский расчёт.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmbeddingResult"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
}
}
},
"202": {
"description": "Операция принята. Опросите GET /requests/{id}.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Request"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
},
"Location": {
"schema": {
"type": "string"
},
"description": "Путь GET /api/v1/requests/{id}."
},
"Preference-Applied": {
"schema": {
"type": "string",
"const": "respond-async"
}
}
}
},
"502": {
"description": "Генерация завершилась ошибкой. Проверьте billing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerationError"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
}
}
},
"default": {
"description": "Ошибка валидации, настроек, доступа или баланса.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
}
}
}
}
}
},
"/rerank": {
"post": {
"operationId": "createRerank",
"summary": "Переранжирование документов",
"description": "JSON-объект. Действуют ограничения выбранной модели и серверного окружения. Параметры допускаются только совместимым проверенным маршрутом; неподдержанные поля не отбрасываются. Повтор с прежним Idempotency-Key возвращает существующую операцию. После очистки её содержимого возвращается 410.",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 191,
"pattern": "^[A-Za-z0-9._:\\-]+$"
},
"description": "Область ключа — клиент. Изменение параметров с прежним ключом даёт 409."
},
{
"name": "Prefer",
"in": "header",
"schema": {
"type": "string"
},
"description": "respond-async: вернуть собственный ID без ожидания поставщика, в том числе при stream=true. Формат тела и Idempotency-Key сохраняются. Готовый повтор возвращает сохранённый результат."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RerankInput"
}
}
}
},
"responses": {
"200": {
"description": "Готовый результат и клиентский расчёт.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RerankResult"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
}
}
},
"202": {
"description": "Операция принята. Опросите GET /requests/{id}.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Request"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
},
"Location": {
"schema": {
"type": "string"
},
"description": "Путь GET /api/v1/requests/{id}."
},
"Preference-Applied": {
"schema": {
"type": "string",
"const": "respond-async"
}
}
}
},
"502": {
"description": "Генерация завершилась ошибкой. Проверьте billing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerationError"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
}
}
},
"default": {
"description": "Ошибка валидации, настроек, доступа или баланса.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
}
}
}
}
}
},
"/decisions": {
"post": {
"operationId": "createDecisions",
"summary": "Структурированные решения",
"description": "JSON-объект. Действуют ограничения выбранной модели и серверного окружения. Параметры допускаются только совместимым проверенным маршрутом; неподдержанные поля не отбрасываются. Повтор с прежним Idempotency-Key возвращает существующую операцию. После очистки её содержимого возвращается 410.",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 191,
"pattern": "^[A-Za-z0-9._:\\-]+$"
},
"description": "Область ключа — клиент. Изменение параметров с прежним ключом даёт 409."
},
{
"name": "Prefer",
"in": "header",
"schema": {
"type": "string"
},
"description": "respond-async: вернуть собственный ID без ожидания поставщика, в том числе при stream=true. Формат тела и Idempotency-Key сохраняются. Готовый повтор возвращает сохранённый результат."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DecisionInput"
}
}
}
},
"responses": {
"200": {
"description": "Готовый результат и клиентский расчёт.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DecisionResult"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
}
}
},
"202": {
"description": "Операция принята. Опросите GET /requests/{id}.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Request"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
},
"Location": {
"schema": {
"type": "string"
},
"description": "Путь GET /api/v1/requests/{id}."
},
"Preference-Applied": {
"schema": {
"type": "string",
"const": "respond-async"
}
}
}
},
"502": {
"description": "Генерация завершилась ошибкой. Проверьте billing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerationError"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
}
}
},
"default": {
"description": "Ошибка валидации, настроек, доступа или баланса.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"X-Generation-ID": {
"schema": {
"$ref": "#/components/schemas/PublicId"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"ClientKey": {
"type": "http",
"scheme": "bearer",
"description": "API-ключ клиента Formula AI."
}
},
"schemas": {
"PublicId": {
"type": "string",
"pattern": "^[a-f0-9]{32}$"
},
"Billing": {
"type": "object",
"properties": {
"currency": {
"const": "RUB"
},
"charged": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{7}$",
"description": "Рубли, точная десятичная строка с 7 знаками."
},
"refunded": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{7}$",
"description": "Рубли, точная десятичная строка с 7 знаками."
},
"status": {
"enum": [
"pending",
"confirmed"
]
}
},
"required": [
"currency",
"charged",
"refunded",
"status"
]
},
"Usage": {
"type": "object",
"description": "Применимые единицы: prompt_tokens, completion_tokens, total_tokens, input_tokens, output_tokens, token_details, images, videos, audio_seconds, duration_seconds. Счётчики могут быть точными численными строками. Поля себестоимости не выдаются."
},
"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"
]
},
"GenerationError": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail"
},
"request_id": {
"$ref": "#/components/schemas/PublicId"
},
"billing": {
"$ref": "#/components/schemas/Billing"
}
},
"required": [
"error",
"request_id",
"billing"
]
},
"Request": {
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/PublicId"
},
"object": {
"const": "ai_service.request"
},
"model": {
"type": "string"
},
"operation": {
"type": "string"
},
"status": {
"enum": [
"queued",
"running",
"waiting",
"saving_media",
"uncertain",
"completed",
"failed",
"cancelled"
]
},
"created_at": {
"type": [
"string",
"null"
],
"description": "Время сервиса Europe/Moscow: YYYY-MM-DD HH:mm:ss, возможно дробная часть секунд."
},
"finished_at": {
"type": [
"string",
"null"
],
"description": "Время сервиса Europe/Moscow: YYYY-MM-DD HH:mm:ss, возможно дробная часть секунд."
},
"content_expires_at": {
"type": [
"string",
"null"
],
"description": "Время сервиса Europe/Moscow: YYYY-MM-DD HH:mm:ss, возможно дробная часть секунд."
},
"content_expired": {
"type": "boolean"
},
"usage": {
"$ref": "#/components/schemas/Usage"
},
"billing": {
"$ref": "#/components/schemas/Billing"
},
"result": {
"type": [
"object",
"null"
],
"description": "Результат выбранной операции. Файлы — только адреса Formula AI либо запрошенный base64."
},
"error": {
"anyOf": [
{
"$ref": "#/components/schemas/ErrorDetail"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"object",
"model",
"operation",
"status",
"created_at",
"finished_at",
"content_expires_at",
"content_expired",
"usage",
"billing",
"result",
"error"
]
},
"EmbeddingInput": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1
},
"input": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 1000000
},
{
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000000
}
},
{
"type": "array",
"minItems": 1,
"items": {
"type": "integer",
"minimum": 0
}
},
{
"type": "array",
"minItems": 1,
"items": {
"type": "array",
"minItems": 1,
"items": {
"type": "integer",
"minimum": 0
}
}
}
]
},
"encoding_format": {
"enum": [
"float",
"base64"
]
},
"dimensions": {
"type": "integer",
"minimum": 1,
"maximum": 2147483647
},
"user": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input_type": {
"enum": [
"search_query",
"search_document",
"classification",
"clustering"
]
}
},
"required": [
"model",
"input"
],
"additionalProperties": false
},
"RerankInput": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 1000000
},
"documents": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000000
}
},
"top_n": {
"type": "integer",
"minimum": 1
},
"return_documents": {
"type": "boolean"
}
},
"required": [
"model",
"query",
"documents"
],
"additionalProperties": false
},
"DecisionInput": {
"type": "object",
"properties": {
"model": {
"type": "string",
"minLength": 1
},
"state": {
"type": [
"string",
"object",
"array"
]
},
"questions": {
"type": "object",
"minProperties": 1,
"additionalProperties": {
"type": "object",
"properties": {
"type": {
"enum": [
"noul",
"choice",
"score"
]
},
"instructions": {
"type": "string",
"minLength": 1,
"maxLength": 1000000
},
"criteria": {
"type": [
"object",
"array"
],
"description": "noul: необязательные true/false. choice: 1–255 имён с описанием или null. score: 2–10 строк по порядку."
}
},
"required": [
"type",
"instructions"
]
}
},
"session_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"user": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"model",
"state",
"questions"
],
"additionalProperties": false
},
"EmbeddingResult": {
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/PublicId"
},
"model": {
"type": "string"
},
"usage": {
"$ref": "#/components/schemas/Usage"
},
"ai_service": {
"type": "object",
"properties": {
"request_id": {
"$ref": "#/components/schemas/PublicId"
},
"billing": {
"$ref": "#/components/schemas/Billing"
}
},
"required": [
"request_id",
"billing"
]
},
"data": {
"type": "array",
"items": {
"anyOf": [
{
"type": "array",
"items": {
"type": "number"
}
},
{
"type": "object",
"properties": {
"object": {
"type": "string"
},
"index": {
"type": "integer"
},
"embedding": {
"type": [
"array",
"string"
]
}
},
"required": [
"embedding"
]
}
]
}
}
},
"required": [
"id",
"model",
"ai_service",
"data"
]
},
"RerankResult": {
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/PublicId"
},
"model": {
"type": "string"
},
"usage": {
"$ref": "#/components/schemas/Usage"
},
"ai_service": {
"type": "object",
"properties": {
"request_id": {
"$ref": "#/components/schemas/PublicId"
},
"billing": {
"$ref": "#/components/schemas/Billing"
}
},
"required": [
"request_id",
"billing"
]
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer"
},
"relevance_score": {
"type": "number"
},
"document": {
"type": [
"string",
"object"
]
}
},
"required": [
"index",
"relevance_score"
]
}
}
},
"required": [
"id",
"model",
"ai_service",
"results"
]
},
"DecisionResult": {
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/PublicId"
},
"model": {
"type": "string"
},
"usage": {
"$ref": "#/components/schemas/Usage"
},
"ai_service": {
"type": "object",
"properties": {
"request_id": {
"$ref": "#/components/schemas/PublicId"
},
"billing": {
"$ref": "#/components/schemas/Billing"
}
},
"required": [
"request_id",
"billing"
]
},
"answers": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
},
"required": [
"id",
"model",
"ai_service",
"answers"
]
}
}
},
"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 сохраняйте включённой.