Как использовать Imagen 4 API? Первая картинка за 5 минут

TL;DR

• Imagen 4 (imagen-4.0) — модель текст-в-изображение, $0.06 за картинку: пишете промпт, выбираете соотношение сторон и получаете изображение; подходит для портретной фотографии, природных крупных планов и продуктовых натюрмортов. Откройте страницу модели, чтобы попробовать онлайн; новым пользователям при регистрации дают 200 кредитов.
• В той же серии есть ещё два уровня: imagen-4.0-fast — $0.03 за картинку для массовых черновиков, imagen-4.0-ultra — $0.09 за картинку для финальных деталей.
• Вызов идёт через интерфейс HiAPI /v1/tasks: отправляете задачу и получаете taskId, затем запрашиваете результат, а после успеха скачиваете картинку из output[0].url.

Что она умеет

• Изображение прямо из текста: референсные изображения не принимаются, картинка полностью описывается промптом, aspect_ratio обязателен (шесть вариантов: 1:1, 16:9, 9:16, 3:4, 4:3, auto).
• Три позиционирования в одной серии: Fast для черновиков, стандартный уровень для повседневного производства, Ultra для повышения детализации; три ID модели используются на разных этапах в одном проекте.
• Всегда ровно 1 изображение за раз: параметров количества, размера в пикселях и формата вывода нет; чтобы получить другое изображение, меняйте seed.

Вот реальный результат стандартного уровня:

Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography

(По-китайски: светлая скандинавская гостиная, льняной диван, дубовые полки и монстера; интерьерная фотография в журнальном стиле. Соотношение сторон 16:9.)

imagen-4.0, 16:9, 1280×720, $0.06.

Сгенерировать с этим промптом →

Как выбрать из трёх моделей

	imagen-4.0-fast	imagen-4.0 (стандарт)	imagen-4.0-ultra
За штуку	$0.03	$0.06	$0.09
Позиционирование	Массовые черновики, выбор направления	Повседневное производство	Детали финального результата, материалы и типографика
На $10 примерно	333 шт.	166 шт.	111 шт.
Подходит для	Обсуждения идей, раунды эскизов	Обычная сдача изображений	Финальные версии, изображения, чувствительные к деталям

Ориентир по бюджету: только стандартный уровень, 1 000 картинок в месяц — около $60.00; чем больше черновиков перенести на Fast, тем ниже счёт, а финальные версии оставляйте Ultra.

Все три модели вызываются одинаково, меняется только поле model; структура параметров совпадает, различается лишь тип seed (см. таблицу параметров). Для Fast и Ultra есть отдельные руководства по подключению на английском: Imagen 4 Fast API guide, Imagen 4 Ultra API guide. Промпты по сценариям смотрите в сборнике промптов; полную таблицу цен и месячный бюджет по трём уровням — на странице цен, а сравнение с Nano Banana 2.1 на двух наборах одинаковых промптов — на странице сравнения.

Два пути освоения

3 шага в браузере: откройте страницу модели → вставьте промпт, выберите соотношение сторон → нажмите «Сгенерировать»; стандартный уровень — $0.06 за картинку. В первый раз советуем прогнать одну картинку в браузере, убедиться, что стиль соответствует ожиданиям, и только потом браться за код.

3 шага через API: POST /v1/tasks — отправить → получить taskId → GET /v1/tasks/<taskId> — дождаться success и скачать.

curl: первая картинка

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "imagen-4.0",
  "input": {
    "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
    "aspect_ratio": "16:9"
  }
}'

Для смены уровня меняйте только model: imagen-4.0-fast или imagen-4.0-ultra. taskId из ответа — это ключ для запроса результата.

Python: отправка, опрос, скачивание

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "imagen-4.0",
    "input": {
        "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
        "aspect_ratio": "16:9",
    },
}

# Отправка: с Idempotency-Key повтор при сетевой ошибке не создаст дубликат задачи
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# Опрос: queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # временный адрес, скачайте и сохраните как можно скорее
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:  # расширение — по фактическому формату ответа
        f.write(img.content)
    print("saved")

Таблица параметров

Поле	Обязательно	Значения	Описание
prompt	Да	1–5000 символов	Описание содержимого изображения
aspect_ratio	Да	1:1 / 16:9 / 9:16 / 3:4 / 4:3 / auto	Соотношение сторон вывода, обязательно
negative_prompt	Нет	≤5000 символов	Содержимое, которого не должно быть
seed	Нет	Стандарт и Ultra: строка (≤500 символов); Fast: целое число	При тех же параметрах и том же seed изображение воспроизводится

Все три модели используют одну и ту же таблицу параметров. Если в теле запроса есть поле вне таблицы, сразу вернётся 400.

Ошибки, которые вы встретите

Код состояния	Значение	Что делать
400 INVALID_REQUEST	Некорректное тело запроса (отсутствует prompt или aspect_ratio, неверное значение перечисления, передано поле вне таблицы)	Исправьте тело запроса по таблице параметров
402 INSUFFICIENT_QUOTA	Недостаточно средств (списание не происходит)	Пополните баланс и повторите
429 RATE_LIMITED	Сработало ограничение частоты	Снизьте частоту отправки
409 / 422 IDEMPOTENCY_KEY_*	Повторная отправка с тем же ключом идемпотентности (в обработке / параметры не совпадают)	Используйте новый Idempotency-Key
415 UNSUPPORTED_MEDIA_TYPE	Неверный формат запроса	Проверьте Content-Type: application/json

Если задача завершается неудачей, среди кодов ошибок также бывают CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT и другие; при неудаче списание не происходит, зарезервированные кредиты возвращаются полностью.

Перед запуском в продакшен

• Callback: передайте на верхнем уровне тела запроса "callback": {"url": "https://..."} — при достижении задачей конечного состояния ваш сервис получит уведомление, и опрос не понадобится.
• Своевременно сохраняйте: output[0].url — временный адрес; получив его, сразу скачивайте и сохраняйте в своё хранилище.
• Указывайте соотношение сторон явно: aspect_ratio — обязательное поле, не полагайтесь на значение по умолчанию; для вертикального контента в соцсетях выбирайте 9:16.
• Тип seed зависит от модели: для Fast передавайте целое число, для стандарта и Ultra — строку.

Частые вопросы

Все три модели вызываются одинаково?

Да, меняется только поле model, остальной код трогать не нужно.

Можно ли указать размер в пикселях или формат вывода?

Нет. Параметров размера в пикселях и формата нет; соотношение сторон вывода определяется aspect_ratio, за раз — 1 изображение.

Списываются ли средства при неудаче?

Нет. Зарезервированные кредиты полностью возвращаются после конечного состояния с ошибкой.

Надёжен ли текст на изображении?

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

Можно ли смешивать изображения трёх уровней в одном проекте?

Да. Логика промптов и соотношения сторон универсальна.

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