Картинки

Понимание изображений

Запросы с картинками идут в POST https://api.aitunnel.ru/v1/chat/completions с параметром messages в формате multi-part. image_url может быть либо URL, либо изображением в формате base64. Несколько изображений можно отправить в отдельных элементах массива content. Количество изображений в одном запросе зависит от провайдера и модели.

Модель должна уметь картинки во входе: в каталоге у неё modalities.input содержит image. Пример ниже — gpt-5.6-sol.

Использование URL изображений

Публичный адрес удобнее: ничего не кодируете на своей стороне.

curl https://api.aitunnel.ru/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Что изображено на этой картинке?"},
          {
            "type": "image_url",
            "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"}
          }
        ]
      }
    ]
  }'

Использование изображений в формате Base64

Для локально хранящихся изображений отправьте их как data-URI data:image/jpeg;base64,... (подставьте MIME файла).

# url — data-URI: data:image/jpeg;base64,<...>
curl https://api.aitunnel.ru/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Что изображено на этой картинке?"},
          {
            "type": "image_url",
            "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQ..."}
          }
        ]
      }
    ]
  }'

Опционально у image_url есть detail: auto (по умолчанию), low или high.

Поддерживаемые типы изображений:

• image/png
• image/jpeg
• image/webp
• image/gif

Какие чат-модели видят картинки — группа chat публичного каталога, фильтр по modalities.input:

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

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

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

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

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

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

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

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

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

Тарификация

• min_price_per_image / max_price_per_image — это ориентировочный диапазон, а не точная цена: у большинства моделей реальная стоимость зависит от разрешения и фактического объёма сгенерированных данных.
• У части моделей цена фиксирована за изображение и задаётся только параметром resolution, а референсы её не меняют. Например, flux-3-image-klein стоит 1,60 ₽ за 768, 1,80 ₽ за 1K, 2,20 ₽ за 1.5K, 2,80 ₽ за 2K и 7,20 ₽ за 4K, flux-3-image — 7,38 ₽ за 768, 8,64 ₽ за 1K, 12,60 ₽ за 1.5K, 18 ₽ за 2K и 109,26 ₽ за 4K, а seedream-5-0-flash — 3,24 ₽ и в 1K, и в 2K. Резерв при этом всегда считается по самому дорогому тиру (у flux-3-image — 109,26 ₽), а разница возвращается сразу после ответа.
• У моделей с оплатой за токены цена зависит от того, сколько токенов модель потратила на картинку. gemini-nano-banana-2.1 обходится примерно в 6,50 ₽ в 1K, 9,50 ₽ в 2K и 21–22 ₽ в 4K, а референсы добавляют входные токены. hy-image-v3.5-preview стоит 4,32 ₽ за картинку до 4 мегапикселей и 5,76 ₽ за квадрат в 4K, референсы бесплатны. minimax-h3-image — около 4 ₽ в 1K и 2K и около 6 ₽ в 4K (плюс около 0,75 ₽ за каждый референс), minimax-h3-image-highspeed — около 6,50 ₽ в 1K и около 12 ₽ в 4K.
• Перед отправкой запроса мы резервируем максимально возможную стоимость (max_price_per_image × n) на вашем балансе — так работает защита от отрицательного баланса.
• После получения ответа от провайдера мы списываем фактическую стоимость запроса и возвращаем разницу, если она есть.
• Итоговая стоимость в рублях приходит в поле usage.cost_rub того же ответа — отдельного шага подтверждения не требуется, всё происходит синхронно.
• Если баланса или бюджета ключа не хватает на резерв — ответ 402 с типом insufficient_balance или budget_exceeded; нужная сумма — в error.metadata.required_rub.
• Изредка провайдер не присылает стоимость вместе с картинкой. Тогда ответ приходит как обычно, но с заголовком X-AITunnel-Cost-Pending: true и без usage.cost_rub: стоимость мы узнаём после и списываем позже, а если провайдер её так и не назвал — списывается резерв. Подробнее — стоимость считается после ответа.

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

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"
  }'

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

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

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

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

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

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

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

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

Анимированный GIF

Передайте output_format: "gif", чтобы получить зацикленную анимацию вместо одной картинки. Сейчас GIF умеют gpt-image-2.6-flare и gpt-image-2.6-sunburst (признак — gif в supported_output_formats модели). Опишите в prompt сюжет, движение и желаемый цикл:

{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "Обезьяна в зелёном пальто поднимает светящийся фонарь, моргает и снова опускает его на фоне заснеженной хижины. Анимация зациклена.",
  "output_format": "gif",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "quality": "medium"
}

• frame_count — от 2 до 16 кадров, по умолчанию 9.
• frame_duration_ms — от 20 до 2000 мс на кадр, по умолчанию 200 (округляется до 10 мс).
• size — размер одного кадра: auto или WIDTHxHEIGHT со сторонами, кратными 16. Число кадров, размер кадра и n должны укладываться в лимиты модели; слишком мелкий кадр провайдер отклонит ошибкой про минимальный бюджет пикселей — тогда увеличьте size или оставьте auto.
• GIF работает только в /v1/images/generations. /v1/images/edits отвечает 400; output_compression вместе с GIF тоже не поддерживается.
• Ответ — обычный: декодируйте data[i].b64_json из base64 и сохраните байты как .gif, media_type будет image/gif.
• Стоимость считается по токенам изображения, как у остальных моделей: ориентир — 1,5 ₽ за короткую анимацию на quality: low, около 5,6 ₽ за 9 кадров на medium.

import base64
import requests

response = requests.post(
    "https://api.aitunnel.ru/v1/images/generations",
    headers={"Authorization": "Bearer sk-aitunnel-xxx"},
    json={
        "model": "gpt-image-2.6-flare",
        "prompt": "Красный мяч подпрыгивает на белом полу, плоская иллюстрация, бесшовный цикл",
        "output_format": "gif",
        "frame_count": 8,
        "frame_duration_ms": 120,
        "quality": "low",
    },
)

item = response.json()["data"][0]
with open("ball.gif", "wb") as f:
    f.write(base64.b64decode(item["b64_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, image/gif); может отсутствовать, если формат не удалось определить.
• usage.cost_rub — фактическая стоимость запроса в рублях.
• usage.balance — баланс аккаунта после списания.

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

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

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

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

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"], "₽")

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

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

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])

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

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

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

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

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

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

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

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="Добавь солнечные очки на лицо человека"

Принимает те же параметры, что и /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 с упоминанием параметра?

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

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

• Используйте 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
• Видео — понимание в чате и генерация MP4
• Аудио — аудио в чате
• Эмбеддинги — векторы картинок для поиска, не описание и не генерация
• Ошибки и отладка
• Лимиты — файлы в /images/edits до 25 МБ