imagen-4.0-fast API: рабочий запрос генерации изображения по тексту

Imagen 4 Fast — это скоростной уровень в линейке Google Imagen 4, и на hiapi он выполняет генерацию изображения по тексту через тот же унифицированный асинхронный API задач, что и все остальные модели изображений. Это руководство даёт вам действительно рабочий запрос — реальный вызов curl, цикл опроса на Python, точную закрытую входную схему и проверенные на реальных запусках случаи ошибок. Всё ниже было выполнено против production-эндпоинта перед публикацией; taskId и выходные URL в примерах взяты из того самого запуска.

Что вы реализуете

Один вызов превращает текстовый промпт в готовое изображение: отправьте задачу через POST /v1/tasks, опрашивайте до завершения, затем прочитайте URL изображения. Вам понадобится API-ключ hiapi (создайте его в консоли и держите на счёте некоторый объём оплаты по факту использования — см. цены). SDK не нужен; каждый пример здесь — чистый HTTP.

Минимальный рабочий запрос (curl)

Создайте задачу. Идентификатор модели — imagen-4.0-fast, и на этом уровне aspect_ratio обязателен (подробнее ниже):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "input": {
      "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
      "aspect_ratio": "16:9"
    }
  }'

Вызов создания возвращает только дескриптор задачи — не изображение:

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A" }, "message": "success" }

Опрос результата (Python)

Получив taskId, опрашивайте GET /v1/tasks/<id>, пока статус не перейдёт в терминальное состояние. Вот цикл, который я реально запускал:

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

# 1. create the task
created = requests.post(API, headers=HEADERS, json={
    "model": "imagen-4.0-fast",
    "input": {
        "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
        "aspect_ratio": "16:9",
    },
}).json()
task_id = created["data"]["taskId"]

# 2. poll until the task reaches a terminal state
while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
    status = data["status"]
    if status == "success":
        print(data["output"][0]["url"])   # the finished image
        break
    if status == "fail":
        raise RuntimeError(data)
    time.sleep(3)

В моём запуске статус примерно за 12 секунд прошёл handling → archiving → success, а терминальный ответ выглядел так:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A",
    "model": "imagen-4.0-fast",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5D4ZD2X353AHHW3SW8X8N0A-0.webp",
        "expireAt": 1793121346
      }
    ]
  },
  "message": "success"
}

Одна задача возвращает одно изображение WebP. Состояние archiving — нормальное: оно ненадолго задерживается, затем переключается на success.

Входная схема (что сервер реально принимает)

Объект input — это закрытая схема. Он принимает только следующие поля:

Поле	Тип	Обязательно	Описание
prompt	string	Да	Непустая строка; пустая строка возвращает minLength: got 0, want 1.
aspect_ratio	enum	Да	Одно из: 1:1, 16:9, 9:16, 3:4, 4:3, auto. Значения по умолчанию нет.
seed	integer	Нет	Для воспроизводимых запусков. Должно быть JSON-числом, а не строкой.
negative_prompt	string	Нет	Описывает, чего следует избегать на изображении.

У модели нет полей resolution или size — размер вывода определяется aspect_ratio. Любое поле за пределами этой таблицы будет отклонено.

Проверенные случаи ошибок (подводные камни)

Это не догадки — каждый из них является реальным ответом 400, перехваченным с production-эндпоинта.

1. Отсутствует aspect_ratio. Это главная ловушка, когда вы копируете фрагмент кода с базового уровня Imagen 4 или Ultra, потому что там aspect_ratio по умолчанию равен 1:1. На Fast значения по умолчанию нет:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: missing required field \"aspect_ratio\"; prompt: minLength: got 0, want 1" }

2. seed отправлен как строка. Передавайте его как число:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: seed: got string, want integer" }

3. Неизвестное поле (здесь resolution) — закрытая схема отклоняет любое лишнее содержимое:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'resolution' not allowed" }

Обратите внимание на форму: ошибка валидации — это HTTP 400 с error_code: "INVALID_REQUEST", без taskId, а message объединяет ошибки всех полей в одну строку, разделённую ; — поэтому читайте весь текст целиком, а не только первое предложение.

Fast по сравнению с другими уровнями линейки Imagen 4

hiapi размещает три уровня Imagen 4 на абсолютно одинаковом API задач; различается только идентификатор model, поэтому тело запроса выше универсально для всех уровней:

• imagen-4.0-fast — скоростной уровень (страница модели), а также самый дешёвый вариант в линейке. Подходит для итерации по промптам, исследования концепций и массового поиска направлений, то есть генерации множества кандидатов с сохранением нескольких.
• imagen-4.0 — стандартный уровень Imagen 4.
• imagen-4.0-ultra — уровень максимальной детализации для финальных материалов доставки.

Практичный рабочий процесс: прототипируйте на Fast, затем замените строку model на imagen-4.0-ultra для финального рендера, не меняя никакой другой код. Сравните текущую цену за изображение на странице цен.

Замечания для production

• Опрос vs. webhook. Цикл выше — это опрос. В production API задач hiapi также поддерживает webhook: добавьте объект верхнего уровня callback (на том же уровне, что model/input) с url и when: "final", и hiapi отправит POST с деталями задачи, когда она достигнет терминального состояния. Перед тем как полагаться на это, прочитайте документацию асинхронного API о соглашениях доставки и повторных попыток.
• Не отправляйте повторно при нестабильной сети. Каждое создание задачи возвращает новый taskId — дедупликации промптов нет. Если какой-то запрос опроса кратко завершился неудачей, повторно опрашивайте уже сохранённый taskId; повторный POST нужен только если вы так и не получили taskId.
• Выходные URL истекают. output[].url находится на temp.hiapi.ai, а его expireAt — примерно через 7 дней (пример выше истекает 2026-10-28). Немедленно скачайте байты в собственное хранилище; не используйте горячие ссылки.

Связанные материалы

• Страница модели Imagen 4 Fast
• Imagen 4 Ultra — уровень максимальной детализации, та же структура запроса
• Imagen 4 (базовая версия)
• Документация унифицированного асинхронного API задач
• Цены

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

Нужен ли Imagen 4 Fast другой эндпоинт или SDK? Нет. Это POST /v1/tasks плюс "model": "imagen-4.0-fast" — тот же эндпоинт, который используют все модели изображений и видео hiapi. Переключайте уровни, меняя идентификатор модели.

Почему мой запрос возвращает 400 с сообщением “missing required field aspect_ratio”? У Fast нет соотношения сторон по умолчанию (в отличие от базового и Ultra уровней). Всегда отправляйте aspect_ratio из перечисления 1:1 | 16:9 | 9:16 | 3:4 | 4:3 | auto.

Можно ли задать разрешение или размер изображения? Нет — у модели нет полей resolution или size; размер вывода определяется aspect_ratio. Отправка resolution вернёт additional properties 'resolution' not allowed.

seed — строка или число? Число. "seed": 7 работает; "seed": "7" вернёт seed: got string, want integer.

Сколько живёт выходной URL? Примерно 7 дней (expireAt). Скачивайте и сохраняйте немедленно.