Гайды

Как генерировать картинки через API — 5 шагов и ловушка с base64

Иллюстрация: из строки текста по конвейеру выезжает готовая рамка с изображением

Генерировать картинки в чате умеют все. Но как только тебе нужно сто картинок — обложки для статей, аватарки, превью товаров — руками это не делается. Нужен API: одна команда, картинка на диске, дальше цикл.

Сразу предупрежу о главной ловушке, на которой спотыкаются в первый же вечер: API не возвращает ссылку на картинку. Он возвращает саму картинку, закодированную текстом прямо внутри JSON. Люди ждут url, не находят его и решают, что запрос не удался. Ниже — весь путь, включая этот момент.

Шаг 1. Возьми ключ и сразу спрячь его

Заведи ключ API в консоли выбранного сервиса и положи его в переменную окружения, а не в код:

export GEMINI_API_KEY="твой_ключ"

Два правила, которые сэкономят тебе деньги. Первое: ключ не коммитить — только через .env, который лежит в .gitignore. Второе, менее очевидное: не зови этот API из браузера. Ключ в клиентском коде виден любому через инструменты разработчика, а генерация картинок — платная операция. Запрос делает твой сервер. Подробности — в как безопасно хранить ключи.

Шаг 2. Отправь первый запрос

Минимальный рабочий вызов — обычный HTTP-запрос, никаких SDK не нужно:

curl -s -X POST \
  'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image:generateContent' \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{"parts": [{"text": "Рыжий кот спит на стопке книг, тёплый свет, вид сбоку"}]}],
    "generationConfig": {"responseModalities": ["IMAGE"]}
  }' -o resp.json

Обрати внимание на responseModalities — этим ты говоришь «хочу картинку, а не текст». У OpenAI логика та же, но эндпоинт свой, а модель называется gpt-image-2.

Открой resp.json — и вот он, сюрприз шага 3.

Шаг 3. Достань картинку из ответа

Внутри ты увидишь не ссылку, а поле inlineData.data и в нём несколько сотен тысяч символов подряд. Это base64 — способ записать двоичный файл обычными буквами, чтобы он проехал внутри текстового JSON. Само по себе это не картинка: её нужно раскодировать обратно в байты и записать на диск.

python3 -c "
import json, base64
r = json.load(open('resp.json'))
part = [p for p in r['candidates'][0]['content']['parts'] if 'inlineData' in p][0]
open('cat.png','wb').write(base64.b64decode(part['inlineData']['data']))
"

У OpenAI поле называется иначе — data[0].b64_json, — но смысл тот же: раскодируй и запиши.

Побочный эффект base64, о котором полезно знать заранее: он раздувает объём примерно на треть. Поэтому ответ весит больше самой картинки, и хранить изображения в базе в таком виде — плохая идея. Клади файл в хранилище, а в базу — ссылку.

Шаг 4. Крути параметры, а не только слова

Когда первая картинка получена, появляется соблазн улучшать результат исключительно текстом промпта. Но часть настроек живёт в параметрах запроса, и они работают надёжнее:

  • Соотношение сторон. Просить «сделай широкую картинку» словами — лотерея. Для этого есть отдельный параметр (aspectRatio у Gemini, size у OpenAI). Указывай явно.
  • Качество / модель. Есть быстрые и дешёвые модели, есть медленные и точные. Для превью бери первые, для финала — вторые.
  • Референс. Почти все модели принимают вместе с текстом входную картинку. Это самый сильный рычаг: подать образец стиля и попросить «то же самое, но с другим предметом» надёжнее, чем описывать стиль словами.

Шаг 5. Посчитай деньги до цикла

Раньше картинки считали поштучно, теперь всё чаще — токенами, как текст. На практике это значит, что цена зависит от разрешения и качества, а не фиксирована.

Порядок величин сегодня: одна картинка обходится в единицы центов. Поштучно незаметно, но цикл на тысячу обложек — уже ощутимая сумма, а если в коде есть ретрай при ошибке, счёт умножается тихо. Прогони десять штук, посмотри реальный расход в консоли, только потом запускай тысячу.

Что делать, когда картинки в ответе нет

Отдельно про случай, который обязательно случится на длинном прогоне: ответ пришёл со статусом 200, но изображения внутри нет.

Причин две. Либо сработал фильтр безопасности — модели отказываются рисовать узнаваемых людей, чужих персонажей и всё, что похоже на документы. Либо модель решила ответить текстом вместо картинки. В обоих случаях в JSON вместо inlineData будет либо текст, либо поле с причиной отказа.

Наивный код, который сразу лезет в первый элемент списка, тут падает с невнятной ошибкой про индекс — и ты полчаса ищешь баг у себя, хотя всё дело в промпте. Поэтому в скрипте всегда проверяй, что картинка вообще есть, и логируй ответ целиком, когда её нет.

Второе правило для цикла: ограничивай повторы. Если генерация не удалась, соблазн поставить ретрай в цикле велик — но каждая попытка платная, а причина отказа обычно в промпте и сама не исправится. Две попытки, потом пропуск и запись в лог.

Что получится

Один скрипт, которому на вход идёт список описаний, а на выходе лежит папка с готовыми файлами. Дальше это прикручивается куда угодно: обложки к постам, аватарки по нику, картинки товаров по названию. Именно так делаются иллюстрации к статьям, которые ты читаешь.

Почему один и тот же промпт даёт разные картинки?

Так и задумано: в процессе есть элемент случайности, диффузионная модель каждый раз стартует из нового шума. Если нужна повторяемость, ищи в документации параметр стартового числа (seed) — с одинаковым числом и одинаковым промптом результат близок к прежнему.

Можно ли обойтись без своего сервера?

Если проект совсем маленький — генерируй заранее, скриптом с ноутбука, а в приложение клади уже готовые файлы. Сервер нужен ровно тогда, когда картинку заказывает пользователь в реальном времени: тогда кто-то должен держать ключ и считать лимиты.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →