Как генерировать картинки через 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 коротких урока на телефоне.





