Генерация и редактирование изображений

AITUNNEL генерирует изображения по текстовому промпту (text-to-image) через POST /v1/images/generations. Запрос синхронный — ответ с готовым изображением приходит в том же HTTP-ответе, без опроса статуса.

Набор параметров (resolution, aspect_ratio, size, quality, output_format, seed и т.д.) единый для всех моделей. resolution, aspect_ratio и background проверяются строго по возможностям конкретной модели (см. раздел ниже) — недопустимое значение вернёт 400. А size, quality, output_format и seed — универсальные необязательные параметры: их можно передавать для любой модели, мы проверяем только формат значения, а не то, «поддерживает» ли его конкретная модель. Если параметр не имеет смысла для модели, она просто применит его (если может) или проигнорирует — без ошибки.

Нужно отредактировать существующее изображение?

Тот же эндпоинт /v1/images/generations умеет и генерацию по референсным изображениям (image-to-image) — просто добавьте input_references к обычному запросу. Подробности — в разделе «Редактирование существующих изображений».

Поддерживаемые модели

Актуальный список моделей генерации изображений вместе с их возможностями (разрешения, aspect ratio, форматы, лимиты) доступен через публичный эндпоинт:

bash

curl https://api.aitunnel.ru/public/aitunnel/models/images

Также его можно посмотреть на странице моделей.

Каждая запись содержит поля:

Поле	Описание
`provider`	Провайдер модели (например, `openai`, `google`, `bytedance-seed`, `black-forest-labs`, `x-ai`)
`min_price_per_image` / `max_price_per_image`	Ориентировочный диапазон цены за одно изображение в рублях (комиссия включена)
`supported_resolutions`	Поддерживаемые разрешения (например, `1K`, `2K`, `4K`)
`supported_aspect_ratios`	Поддерживаемые соотношения сторон (например, `16:9`, `9:16`, `1:1`)
`supported_quality`	Значения `quality`, которые точно дают эффект у этой модели (например, `low`, `medium`, `high`) — справочно; параметр можно передавать и другим моделям, они просто проигнорируют его без ошибки
`supported_output_formats`	Значения `output_format`, которые точно дают эффект у этой модели (например, `png`, `jpeg`) — справочно, как и `supported_quality`
`supported_background`	Допустимые значения `background` (например, `auto`, `transparent`, `opaque`) — строго проверяется: значение не из списка вернёт `400`
`supports_seed`	Есть ли у модели реальный эффект от параметра `seed` — справочно, как и `supported_quality`
`max_n`	Максимум изображений за один запрос (`n`)
`max_input_references`	Максимум референс-изображений для image-to-image (0 — редактирование не поддерживается)
`supports_generation` / `supports_edit`	Поддерживает ли модель генерацию / редактирование

Тарификация

min_price_per_image / max_price_per_image — это ориентировочный диапазон, а не точная цена: у большинства моделей реальная стоимость зависит от разрешения и фактического объёма сгенерированных данных.
Перед отправкой запроса мы резервируем максимально возможную стоимость (max_price_per_image × n) на вашем балансе — так работает защита от отрицательного баланса.
После получения ответа от провайдера мы списываем фактическую стоимость запроса и возвращаем разницу, если она есть.
Итоговая стоимость в рублях приходит в поле usage.cost_rub того же ответа — отдельного шага подтверждения не требуется, всё происходит синхронно.

Базовая генерация

Python (requests)TypeScriptcURL

python

import requests

response = requests.post(
    "https://api.aitunnel.ru/v1/images/generations",
    headers={"Authorization": "Bearer sk-aitunnel-xxx"},
    json={
        "model": "seedream-4.5",
        "prompt": "Красивый закат над горами, кинематографичный стиль",
        "resolution": "2K",
        "aspect_ratio": "16:9",
    },
)

result = response.json()
b64 = result["data"][0]["b64_json"]
print("Изображение получено, длина base64:", len(b64))
print("Стоимость:", result["usage"]["cost_rub"], "₽")

typescript

const response = await fetch("https://api.aitunnel.ru/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-aitunnel-xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedream-4.5",
    prompt: "Красивый закат над горами, кинематографичный стиль",
    resolution: "2K",
    aspect_ratio: "16:9",
  }),
});

const result = await response.json();
const b64 = result.data[0].b64_json;
console.log("Изображение получено, длина base64:", b64.length);
console.log("Стоимость:", result.usage.cost_rub, "₽");

shell

curl https://api.aitunnel.ru/v1/images/generations \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5",
    "prompt": "Красивый закат над горами, кинематографичный стиль",
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }'

Изображения приходят как base64

В отличие от старой версии API, результат всегда возвращается как base64 в поле data[i].b64_json — прямых URL на изображение больше нет. Декодируйте base64 самостоятельно и сохраняйте файл.

Параметры запроса

Параметр	Тип	Обязательный	Описание
`model`	string	да	ID модели (например, `seedream-4.5`). Список — через публичный эндпоинт моделей
`prompt`	string	да	Текстовое описание изображения
`n`	integer	нет	Количество изображений (1–10 в зависимости от модели, по умолчанию 1). Проверяйте `max_n`
`resolution`	string	нет	Разрешение (например, `1K`, `2K`, `4K`) — должно входить в `supported_resolutions` модели
`aspect_ratio`	string	нет	Соотношение сторон (например, `16:9`, `1:1`) — должно входить в `supported_aspect_ratios` модели
`size`	string	нет	Универсальный опциональный параметр для любой модели — тир (`2K`), точные пиксели `WIDTHxHEIGHT` (например, `1024x1536`, латинская `x`) или `auto`. Необязателен — без него модель отдаёт свой размер по умолчанию. Явные пиксели нельзя комбинировать с `resolution`/`aspect_ratio` в одном запросе
`quality`	string	нет	Универсальный опциональный параметр — `low`, `medium`, `high` или `auto`. Модели без «ручки» качества (`supported_quality` пуст) просто проигнорируют его
`output_format`	string	нет	Универсальный опциональный параметр — `png`, `jpeg`, `webp` или `svg`. Модели без поддержки конкретного формата (`supported_output_formats` пуст) проигнорируют его
`background`	string	нет	Фон (например, `auto`, `transparent`, `opaque`) — единственный из этой группы параметров, который строго проверяется: значение должно входить в `supported_background` модели, иначе `400`
`output_compression`	integer	нет	Сжатие для `jpeg`/`webp`, 0–100
`seed`	integer	нет	Универсальный опциональный параметр — seed для детерминизма. Модели без реальной поддержки (`supports_seed: false`) просто проигнорируют его
`input_references`	array	нет	Референсные изображения для image-to-image — см. раздел ниже

Строго проверяются только resolution/aspect_ratio/background

resolution, aspect_ratio и background должны входить в соответствующие supported_* поля модели — иначе 400 Bad Request. size, quality, output_format и seed — универсальные и необязательные: их можно передавать любой модели, мы проверяем только формат значения. Если параметр не имеет смысла для конкретной модели, она либо применит его сама, либо тихо проигнорирует — без ошибки.

Провайдер-специфичные параметры

Некоторые модели принимают дополнительные параметры, специфичные для конкретного провайдера (например, moderation для моделей семейства GPT Image). Список таких параметров для модели — в поле allowed_passthrough_parameters публичного эндпоинта моделей. Передавайте их прямо на верхнем уровне запроса, как обычный параметр:

json

{
  "model": "gpt-image-1",
  "prompt": "Логотип кофейни",
  "moderation": "low"
}

Несколько изображений за раз

Передайте n, если модель поддерживает max_n > 1:

json

{
  "model": "gpt-image-1",
  "prompt": "Логотип кофейни в минималистичном стиле, разные цветовые варианты",
  "n": 4,
  "quality": "medium"
}

Каждый элемент результата — отдельный объект в массиве data.

Формат ответа

json

{
  "created": 1234567890,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "media_type": "image/png"
    }
  ],
  "model": "seedream-4.5",
  "usage": {
    "cost_rub": 3.4,
    "balance": 1245.6
  }
}

data[i].b64_json — base64-код изображения.
data[i].media_type — MIME-тип результата (image/png, image/jpeg, image/webp); может отсутствовать, если формат не удалось определить.
usage.cost_rub — фактическая стоимость запроса в рублях.
usage.balance — баланс аккаунта после списания.

Редактирование существующих изображений (image-to-image)

Чтобы отредактировать существующее изображение, добавьте к обычному запросу генерации параметр input_references — массив объектов с референсными изображениями. Модель использует их как визуальную основу и применяет к ним вашу текстовую инструкцию из prompt. Отдельный эндпоинт для этого не нужен — работает тот же POST /v1/images/generations.

Каждый элемент input_references — объект { "type": "image_url", "image_url": { "url": "..." } } (тот же формат, что и у input_references/frame_images в генерации видео); url — это data: base64-строка для локального файла или публичный HTTP(S)-адрес. Максимальное количество референсов на запрос — в поле max_input_references модели.

Редактирование локального файла

PythonTypeScript

python

import base64
import requests

with open("photo.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.aitunnel.ru/v1/images/generations",
    headers={"Authorization": "Bearer sk-aitunnel-xxx"},
    json={
        "model": "gpt-image-1",
        "prompt": "Добавь солнечные очки на лицо человека",
        "input_references": [
            {
                "type": "image_url",
                "image_url": {"url": f"data:image/png;base64,{b64}"},
            },
        ],
    },
)

result = response.json()
print(result["data"][0]["b64_json"][:50])
print("Стоимость:", result["usage"]["cost_rub"], "₽")

typescript

import fs from "fs";

const b64 = fs.readFileSync("photo.png").toString("base64");

const response = await fetch("https://api.aitunnel.ru/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-aitunnel-xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-image-1",
    prompt: "Добавь солнечные очки на лицо человека",
    input_references: [
      { type: "image_url", image_url: { url: `data:image/png;base64,${b64}` } },
    ],
  }),
});

const result = await response.json();
console.log(result.data[0].b64_json.slice(0, 50));

Комбинирование нескольких локальных файлов

Передайте несколько объектов в input_references, чтобы объединить элементы разных фото в одно изображение (лимит — max_input_references модели):

python

import base64
import requests

def to_data_url(path):
    with open(path, "rb") as f:
        return f"data:image/png;base64,{base64.b64encode(f.read()).decode('utf-8')}"

response = requests.post(
    "https://api.aitunnel.ru/v1/images/generations",
    headers={"Authorization": "Bearer sk-aitunnel-xxx"},
    json={
        "model": "seedream-4.5",
        "prompt": "Помести человека с первого фото на фон пляжа со второго фото",
        "input_references": [
            {"type": "image_url", "image_url": {"url": to_data_url("person.png")}},
            {"type": "image_url", "image_url": {"url": to_data_url("beach.png")}},
        ],
    },
)

result = response.json()
print(result["data"][0]["b64_json"][:50])

Прозрачный фон при редактировании

json

{
  "model": "gpt-image-1",
  "prompt": "Удали фон, оставь только товар",
  "input_references": [
    { "type": "image_url", "image_url": { "url": "data:image/png;base64,<...>" } }
  ],
  "background": "transparent"
}

Если изображение уже доступно по URL

Так же можно указать публичный HTTP(S)-адрес напрямую, без кодирования:

json

{
  "model": "gpt-image-1",
  "prompt": "Добавь солнечные очки на лицо человека",
  "input_references": [
    { "type": "image_url", "image_url": { "url": "https://example.com/photo.png" } }
  ]
}

Также поддерживается: `POST /v1/images/edits`

Для удобства клиентов, привыкших к OpenAI Images API, у нас также есть отдельный эндпоинт POST /v1/images/edits, который принимает файлы напрямую через multipart/form-data (без ручного base64-кодирования) и под капотом делает то же самое, что и input_references выше:

shell

curl https://api.aitunnel.ru/v1/images/edits \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -F model="gpt-image-1" \
  -F image="@photo.png" \
  -F prompt="Добавь солнечные очки на лицо человека"

Принимает те же параметры, что и /v1/images/generations, плюс image (файл, до 25 МБ) и image[] (несколько файлов вместо image).

Лучшие практики

Чёткие промпты — указывайте стиль, цвета, композицию и настроение. Для редактирования — конкретно называйте область и желаемый результат.
Выбор модели — Gemini и Seedream хорошо справляются с художественными и смешанными запросами, Flux — с фотореализмом, GPT Image — с точным следованием инструкциям и текстом на изображении.
Сверяйтесь с capability-полями модели — не все модели принимают одинаковый набор параметров (resolution vs size, quality, background и т.д.), и не все поддерживают input_references (проверяйте max_input_references).
Явно указывайте n только если нужно больше одного изображения — по умолчанию генерируется одно.
Хранение — декодируйте base64 и сохраняйте файл; не храните сырые base64-строки в БД, если изображений много.

Устранение неполадок

400 Bad Request с упоминанием параметра?

Строго проверяются только resolution, aspect_ratio, background и input_references — значение должно входить в соответствующие capability-поля модели из публичного эндпоинта /public/aitunnel/models/images.
size, quality, output_format и seed — универсальные параметры, проверяется только формат значения (не список моделей). Если получили 400 именно на одном из них — проверьте формат: size должен быть тиром (2K), пикселями WIDTHxHEIGHT (латинская x) или auto; quality — auto/low/medium/high; output_format — png/jpeg/webp/svg; seed — число.

Модель не найдена?

Используйте ID модели без префикса провайдера (например, seedream-4.5, а не bytedance-seed/seedream-4.5).
Актуальный список — GET https://api.aitunnel.ru/public/aitunnel/models/images и страница моделей.

Модель не поддерживает редактирование?

Проверьте max_input_references и supports_edit в публичном эндпоинте моделей — не у всех моделей каталога есть поддержка image-to-image.

Смотрите также

Изображения и PDF — отправка изображений на вход моделям chat/completions (анализ, описание, OCR).
Генерация видео — асинхронная генерация видео.
Методы AITUNNEL — список всех поддерживаемых эндпоинтов.

Генерация и редактирование изображений ​

Поддерживаемые модели ​

Тарификация ​

Базовая генерация ​

Параметры запроса ​

Провайдер-специфичные параметры ​

Несколько изображений за раз ​

Формат ответа ​

Редактирование существующих изображений (image-to-image) ​

Редактирование локального файла ​

Комбинирование нескольких локальных файлов ​

Прозрачный фон при редактировании ​

Если изображение уже доступно по URL ​

Также поддерживается: POST /v1/images/edits ​

Лучшие практики ​

Устранение неполадок ​

Смотрите также ​

Генерация и редактирование изображений

Поддерживаемые модели

Тарификация

Базовая генерация

Параметры запроса

Провайдер-специфичные параметры

Несколько изображений за раз

Формат ответа

Редактирование существующих изображений (image-to-image)

Редактирование локального файла

Комбинирование нескольких локальных файлов

Прозрачный фон при редактировании

Если изображение уже доступно по URL

Также поддерживается: `POST /v1/images/edits`

Лучшие практики

Устранение неполадок

Смотрите также