imagen-4.0-ultra API: рабочий запрос текст-в-изображение

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

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

Один вызов превращает текстовый промпт в готовое изображение: отправьте задачу в POST /v1/tasks, опрашивайте до завершения, затем прочитайте URL изображения из output[0].url. Вам понадобится API-ключ hiapi — получите его в своём личном кабинете и экспортируйте:

export HIAPI_API_KEY="your-hiapi-key"

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

Модель принимает prompt и необязательный aspect_ratio. Создайте задачу:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-ultra",
    "input": {
      "prompt": "Macro product photo of a matte ceramic coffee mug on a pale oak table, soft window light from the left, shallow depth of field, a few coffee beans in the foreground, no text, no logos",
      "aspect_ratio": "4:3"
    }
  }'

Вызов создания сразу возвращает id задачи — генерация продолжается в фоне:

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

Опрашивайте задачу по возвращённому id:

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Когда status равен success, изображение находится в output[0].url:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61",
    "model": "imagen-4.0-ultra",
    "status": "success",
    "storage": "temp",
    "created": 1792506471,
    "completed": 1792506479,
    "output": [
      {
        "artifactId": "279760",
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5CVC8R62M0Z7CCM8WB38B61-0.webp",
        "expireAt": 1793111279
      }
    ]
  },
  "message": "success"
}

Тот запуск завершился примерно за 8 секунд и вернул WebP (не PNG/JPEG). URL находится во временном хранилище ("storage": "temp"), а expireAt установлен на 7 дней вперёд — скачивайте вовремя, не используйте горячие ссылки.

Продакшн: Python с циклом опроса

Ответ создания не содержит изображения — только taskId. Настоящая интеграция сначала отправляет задачу, затем опрашивает её (или использует callback). Этот скрипт выполняет полный цикл и сразу скачивает результат, поскольку URL временный:

import os, time, requests

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

def generate(prompt, aspect_ratio="1:1", negative_prompt=None, seed=None):
    body = {"model": "imagen-4.0-ultra", "input": {"prompt": prompt, "aspect_ratio": aspect_ratio}}
    if negative_prompt:
        body["input"]["negative_prompt"] = negative_prompt
    if seed is not None:
        body["input"]["seed"] = str(seed)  # seed is a STRING, not a number

    r = requests.post(API, headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    created = r.json()
    if created.get("code") != 200:
        raise RuntimeError(f"create rejected: {created}")
    task_id = created["data"]["taskId"]

    # Poll. Statuses other than success/fail (e.g. queued, running, archiving) mean "keep waiting".
    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # tolerate a transient read; re-poll the same id
        status = d.get("status")
        if status == "success":
            return d["output"][0]["url"]
        if status in ("fail", "failed", "error"):
            raise RuntimeError(f"task failed: {d}")
    raise TimeoutError(f"task {task_id} did not finish in time")

url = generate(
    "A high-detail aerial landscape of terraced rice fields at golden hour, long shadows",
    aspect_ratio="16:9",
)
img = requests.get(url, timeout=60).content
open("out.webp", "wb").write(img)
print(f"saved {len(img)} bytes from {url}")

Важные моменты для продакшна:

• Опрос vs callback. Выше показан опрос. Чтобы избежать опроса, можно прикрепить объект callback верхнего уровня ({"url": "...", "when": "final"}) — hiapi отправит вам POST-запрос, когда задача достигнет терминального состояния. Контракт callback описан в документации унифицированного асинхронного API.
• Повторно опрашивайте сохранённый id, не создавайте заново. Чтение задачи идемпотентно; при обрыве соединения повторяйте GET /v1/tasks/<id>, никогда не делайте повторный POST (это billed бы ещё одно изображение).
• Скачивайте сразу после успеха. output[0].url временный (в этом запуске TTL составил 7 дней). Заберите байты и перенесите в собственное хранилище.

Параметры, которые модель фактически принимает

imagen-4.0-ultra поддерживает только текст-в-изображение — референсные изображения не поддерживаются (подтверждено на странице модели; в этом запуске тестировался только текст-в-изображение). Входная схема закрытая: неизвестные поля отклоняются, поэтому тайком передать лишние параметры не получится.

Поле	Тип	Обязательно	Описание
prompt	string	да	1–5 000 символов. Пустая строка завершится ошибкой (minLength: got 0, want 1).
aspect_ratio	enum	нет	Одно из 1:1, 16:9, 9:16, 3:4, 4:3, auto. По умолчанию 1:1.
negative_prompt	string	нет	До 5 000 символов; описывает, что нужно исключить.
seed	string	нет	До 500 символов. Это строка — передача числа будет отклонена.

Один запрос генерирует ровно одно изображение.

Проверенные случаи ошибок

Все они получены на реальном эндпоинте, поэтому ваша обработка ошибок может на них полагаться. Отклонённые запросы возвращают HTTP 400 с плоским конвертом и без taskId:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: aspect_ratio: value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'"}

Несколько поведений, которые стоит учесть в коде:

• Валидатор сообщает обо всех ошибках полей сразу, соединяя их через ; . Если передать число в seed и некорректный aspect_ratio, вы получите обе ошибки в одном сообщении: invalid input: seed: got number, want string; aspect_ratio: value must be one of .... Не предполагайте, что в ответе будет только одна ошибка.
• Неизвестные поля приводят к сбою всего запроса с ошибкой <root>: additional properties '<name>' not allowed. Схема закрытая.
• Пустой промпт завершается ошибкой prompt: minLength: got 0, want 1.
• Успешный create — это code: 200 с data.taskId; при отклонении — data: null. Разветвляйтесь по этому признаку, прежде чем пытаться прочитать id задачи.

Какой уровень Imagen 4 вызывать?

imagen-4.0-ultra — старший из трёх уровней; выбирайте по задаче, а не по привычке (соотношение сторон, негативный промпт и seed не влияют на то, сколько вы платите — см. цены):

• Imagen 4 Fast — самый дешёвый, подходит для черновых прогонов и массового поиска направлений.
• Imagen 4 — повседневный средний уровень, подходит для продуктовых, лайфстайл- и контентных изображений.
• Imagen 4 Ultra (эта модель) — самый дорогой из трёх, ориентирован на готовую детализацию: макротекстуры, рендеринг материалов и типографику, для случаев, когда финальное изображение должно выдерживать пристальное рассмотрение. Выбирайте Ultra, когда результат можно отдавать сразу; для итераций используйте Fast или базовый уровень.

Полезные ссылки

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

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

Сколько изображений возвращает один запрос? Одно. В проверенном запуске массив output содержал только один элемент.

В каком формате вывод? WebP. Возвращаемый файл — .webp на temp.hiapi.ai.

Сколько действует URL вывода? Около 7 дней — expireAt установлен на 7 дней после завершения. Считайте его временным ресурсом и скачивайте сразу.

Можно ли отправлять референсные изображения? Нет. imagen-4.0-ultra поддерживает только текст-в-изображение; на странице модели референсные изображения указаны как неподдерживаемые.

Почему мой запрос возвращает ошибку "additional properties not allowed"? Входная схема закрытая. Отправляйте только prompt, aspect_ratio, negative_prompt и seed; любой другой ключ приводит к сбою всего запроса.

Влияют ли негативный промпт, seed или соотношение сторон на цену? Нет. Оплата за изображение; эти параметры не влияют на стоимость.