Изображения

Гайды

POST /images или /images/generations создаёт изображение. Для генерации требуется prompt; для правки передавайте input_references. Вариации без prompt доступны только у маршрутов, подтверждающих такую возможность; несовместимое сочетание отклоняется до генерации. Доступные размеры, качество, число изображений и маска зависят от модели.

Входной файл — HTTPS URL или data URI base64. Изображения-референсы передаются как строки либо объекты type=image_url, image_url.url. Сервер проверяет формат и размер, запрещает локальные и частные адреса.

response_format=url возвращает адрес файла Formula AI; для получения файла передайте тот же Bearer. response_format=b64_json возвращает base64 из собственного хранилища. Технические адреса поставщиков клиенту не выдаются.

Модели с операцией image_chat также принимают messages через /chat/completions; результат может содержать choices.message.images. HTTP 202 означает ожидание сохранения результата: продолжайте опрос собственного запроса.

Проверяйте срок хранения: истёкший файл возвращает 410. Численные ограничения задаёт администратор; расширение размеров не означает поддержку конкретной моделью.

cURL · POST /images

bash

curl "https://formula-ai.ru/api/v1/images" \
  -H "Authorization: Bearer $AI_SERVICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-images-1" \
  --data-binary "{
    \"model\": \"$AI_SERVICE_MODEL\",
    \"prompt\": \"A red circle on a white background\",
    \"response_format\": \"url\"
}"

cURL · POST /images

bash

curl "https://formula-ai.ru/api/v1/images" \
  -H "Authorization: Bearer $AI_SERVICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-image_edit-1" \
  --data-binary "{
    \"model\": \"$AI_SERVICE_MODEL\",
    \"prompt\": \"Change the background to blue\",
    \"input_references\": [
        {
            \"type\": \"image_url\",
            \"image_url\": {
                \"url\": \"https://example.com/source.png\"
            }
        }
    ]
}"

PHP · POST /images

<?php
$key = getenv("AI_SERVICE_API_KEY");
$url = "https://formula-ai.ru/api/v1/images";
$handle = curl_init($url);
curl_setopt_array($handle, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(["model" => getenv("AI_SERVICE_MODEL"), "prompt" => "A red circle on a white background"], JSON_THROW_ON_ERROR),
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . $key, "Content-Type: application/json", "Idempotency-Key: php-images-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 /images

<?php
$key = getenv("AI_SERVICE_API_KEY");
$url = "https://formula-ai.ru/api/v1/images";
$handle = curl_init($url);
curl_setopt_array($handle, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(["model" => getenv("AI_SERVICE_MODEL"), "prompt" => "A red circle on a white background", "input_references" => [getenv("AI_SERVICE_SOURCE_URL")]], JSON_THROW_ON_ERROR),
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . $key, "Content-Type: application/json", "Idempotency-Key: php-image_edit-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);

Примеры 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 сохраняйте включённой.