Imagen 4 для изображений товаров в электронной коммерции: промпты, пакетный код и контроль качества

Краткий обзор

• Стандартная версия Imagen 4 работает на HiAPI под идентификатором imagen-4.0 по цене $0.06 за изображение, генерирует одно изображение на запрос и поддерживает только генерацию из текста. Откройте страницу модели Imagen 4, чтобы сначала опробовать один промпт.
• Для товарного каталога она хорошо подходит для создания изображений товаров на белом фоне и лайфстайл-снимков, для которых иначе потребовалась бы отдельная съёмка каждого цветового варианта. Но она не воспроизводит ваш реальный SKU, поскольку не принимает входные изображения-референсы.
• aspect_ratio — обязательное поле (без значения по умолчанию), а seed должен быть строкой из цифр. В наших запусках "seed": "sku-dripper-01" проходил валидацию, но примерно через секунду каждая задача завершалась с ошибкой TASK_FAILED.
• Заложите этап контроля качества. В пакете из 4 изображений мы получили незапрошенный стеклянный чайник, глянцевую глазурь там, где требовалась матовая, и поддельный текст на реквизите — несмотря на negative_prompt: "text, logo".

Что охватывает это руководство

Это практический рабочий процесс для интернет-магазина по созданию набора изображений для продуктовой линейки: одно каталожное изображение на белом фоне для каждого SKU, одно лайфстайл-изображение для страницы товара и одна вертикальная обрезка для мобильных историй. Всё ниже было запущено 2026-11-04 против живого API на вымышленном продукте: серо-зелёной керамической воронке для пуровера и подходящей кружке.

Если вам нужно просто заставить первый запрос работать, начните с руководства по использованию Imagen 4 API. Универсальные шаблоны промптов см. в руководстве по промптам Imagen 4. Это руководство о том, как пакетно генерировать наборы изображений для магазина и проверять их перед публикацией.

Выберите уровень до написания промптов

Все три уровня Imagen 4 на HiAPI — это генерация из текста с одинаковой структурой запроса: чтобы переключить уровень, достаточно изменить идентификатор model. Цены взяты из тарифов HiAPI на день тестирования.

Уровень	Идентификатор модели	Цена за изображение	Страница модели
Fast	imagen-4.0-fast	$0.03	Imagen 4 Fast
Standard	imagen-4.0	$0.06	Imagen 4
Ultra	imagen-4.0-ultra	$0.09	Imagen 4 Ultra

Для товарного каталога арифметика проста. 200 SKU × (1 изображение товара + 1 лайфстайл-изображение) = 400 изображений: $24 на уровне Standard, $12 на Fast, $36 на Ultra — и это без учёта любых повторных попыток. В этой статье тестировался только уровень Standard, поэтому никаких утверждений о качестве Fast или Ultra не делается. Полную разбивку цен см. в руководстве по ценам Imagen 4 API.

Запрос: четыре поля, два из которых легко ошибиться

Схема входных данных imagen-4.0 закрытая. Ниже — пограничные случаи, с которыми мы столкнулись при построении пакетной обработки, с точными сообщениями об ошибках:

Поле	Правило	Что мы наблюдали
prompt	Обязательная строка	—
aspect_ratio	Обязательное, одно из значений 1:1, 16:9, 9:16, 3:4, 4:3, auto	При пропуске: aspect_ratio: missing required field "aspect_ratio". При "2:1": value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'
negative_prompt	Необязательная строка	Принимается. Уменьшил текст на реквизите, но не устранил его (см. контроль качества)
seed	Необязательная строка	Число (12): seed: got number, want string. Нецифровая строка ("sku-dripper-01"): принимается с HTTP 200, затем задача завершается с TASK_FAILED. Цифровая строка ("1042"): работает нормально
Любое другое содержимое	Отклоняется	additional properties 'foo' not allowed

Проблема с seed стоила нам лишнего раунда. Заманчиво использовать код SKU в качестве seed для прослеживаемости при повторных запусках, и валидатор это пропускал. Все четыре задачи из нашей первой партии вернули такой результат:

{"code":200,"data":{"error":{"code":"TASK_FAILED","message":"task failed"},"model":"imagen-4.0","status":"fail"}}

Затем мы по одному убирали поля. Тот же промпт только с negative_prompt сработал, только с "seed": "sku-dripper-01" — упал, а с "seed": "1042" — сработал. Оставляйте seed числовым, а сопоставление SKU храните в собственной таблице задач.

Размер выходного изображения зависит от пропорций. В наших запусках 1:1 возвращал 1024×1024, 4:3 — 1152×864, 9:16 — 720×1280, все в формате WebP. Если для вашего магазина нужны увеличенные изображения 2000 px, запланируйте отдельный этап апскейла. Сам вывод таким большим не будет.

Промпты для каталожных наборов

Пишите шаблоны промптов по типу съёмки, а не по товару, затем подставляйте описание товара. Сохраняйте одинаковое освещение, ракурс камеры и фон у всех SKU, чтобы сетка изображений выглядела как один каталог.

Изображение товара (1:1). Укажите фон, композицию, одно направление света и желаемую тень:

Studio packshot of a matte sage-green ceramic coffee mug with a thin loop handle
on a seamless pure white background, centered, handle pointing right, eye-level view,
soft diffused key light from the left, gentle contact shadow, e-commerce catalog photography

Кружка получилась чисто: ручка направлена вправо, как требовалось, тень мягкая, фон равномерный. Никакого редактирования не потребовалось.

Лайфстайл-изображение (4:3). Укажите главный объект, поверхность, направление света и какие предметы должны быть не в фокусе. Затем снова подчеркните, что товар — чёткий главный объект:

Lifestyle product photo: a matte sage-green ceramic pour-over dripper sitting on a glass carafe
on a light oak kitchen counter, morning window light from the right, a bag of coffee beans and a
gooseneck kettle softly out of focus in the background, warm natural tones, shallow depth of field,
the dripper is the sharp hero of the frame

Этот промпт создал изображение в начале статьи.

Вертикальное изображение для истории (9:16). Если сверху будет заголовок, явно попросите оставить свободное пространство:

Vertical lifestyle product photo for a mobile story: overhead flat lay of a matte sage-green ceramic
pour-over dripper on a linen napkin, scattered roasted coffee beans, a small ceramic cup of black coffee,
on a pale stone surface, soft even daylight, generous empty space in the top third for a headline

Верхняя треть пустая, как и требовалось. Но обратите внимание: целые кофейные зёрна лежат внутри воронки — так кофе никто не заваривает, и покупатели кофе это заметят. Подробнее ниже.

Код асинхронной пакетной обработки

Генерация изображений на HiAPI асинхронная: POST /v1/tasks возвращает taskId, затем нужно опрашивать GET /v1/tasks/{taskId}, пока status не станет success или fail (см. документацию по асинхронному API). Для товарного каталога отправьте все задачи сразу и опрашивайте их параллельно. Это скрипт, который мы запускали; промпты сокращены. Два лайфстайл-изображения получены непосредственно этим скриптом. Два изображения товара были сгенерированы по одному с теми же промптами, когда мы разбирались с описанным выше сбоем seed (изображение воронки без seed).

import os, time, json, concurrent.futures as cf
import requests

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

NEG = "text, logo, watermark, hands, people, clutter, reflections of camera"

JOBS = [
    {"sku": "dripper-white", "aspect_ratio": "1:1", "seed": "1041", "prompt": "Studio packshot of ..."},
    {"sku": "mug-white",     "aspect_ratio": "1:1", "seed": "1042", "prompt": "Studio packshot of ..."},
    {"sku": "dripper-scene", "aspect_ratio": "4:3", "seed": "2041", "prompt": "Lifestyle product photo: ..."},
    {"sku": "dripper-story", "aspect_ratio": "9:16", "seed": "3041", "prompt": "Vertical lifestyle product photo ..."},
]

def submit(job):
    body = {"model": "imagen-4.0",
            "input": {"prompt": job["prompt"], "aspect_ratio": job["aspect_ratio"],
                      "negative_prompt": NEG, "seed": job["seed"]}}  # seed: digits only
    r = requests.post(API, headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        data = r.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(4)
    raise TimeoutError(task_id)

def run(job):
    t0 = time.time()
    task_id = submit(job)
    data = wait(task_id)
    if data["status"] != "success":
        return {"sku": job["sku"], "status": "fail", "error": data.get("error")}
    url = data["output"][0]["url"]
    img = requests.get(url, timeout=60).content
    path = f"{job['sku']}.webp"
    open(path, "wb").write(img)          # download now: output URLs expire
    return {"sku": job["sku"], "status": "success", "task_id": task_id,
            "seconds": round(time.time() - t0, 1), "bytes": len(img), "file": path}

with cf.ThreadPoolExecutor(max_workers=4) as pool:
    for result in pool.map(run, JOBS):
        print(json.dumps(result))

В продакшене важны три детали:

1. Неудачные задачи всё равно возвращают HTTP 200. Проверяйте data.status == "fail" и data.error.code. Не полагайтесь только на raise_for_status().
2. Скачивайте сразу. output[0].url — это временная ссылка с меткой времени expireAt (в наших ответах — примерно через 7 дней). Копируйте байты в собственное хранилище или CDN. Не используйте горячую ссылку на этот URL из вашего магазина.
3. Записывайте идентификатор задачи рядом с SKU. Когда проверяющий отклонит изображение, вам нужно знать промпт, seed и идентификатор задачи, сгенерировавшие его.

В наших запусках одна задача завершалась на сервере за 7–8 секунд (created → completed). Две параллельные лайфстайл-задачи заняли 31 и 42 секунды реального времени, включая 4-секундный интервал опроса и загрузку. При max_workers=4 в небольших пакетах преобладают накладные расходы на опрос, а не время генерации.

Контроль качества: что проверять перед публикацией изображений

Генерация из текста создаёт правдоподобные товары, а не фотографию именно того изделия, что лежит на вашем складе. Каждое изображение нужно проверять вручную или автоматически на соответствие реальному SKU. Вот проблемы, которые мы нашли в пакете из 4 изображений:

Проверка	Что было в нашем пакете	Как исправить
В кадре только перечисленные товары	К изображению воронки был добавлен подходящий зелёный стеклянный чайник с ручкой, которого промпт вовсе не требовал (см. изображение выше).	Добавьте «single object, nothing else in frame» и повторите попытку. Никогда не публикуйте набор, который вы не продаёте.
Поверхность и материал	Мы просили матовую глазурь. Оба изображения воронки получились глянцевыми. Кружка вышла ближе к сатиновой.	Воспринимайте слова о материале как подсказку. Сравнивайте с реальным товаром и отклоняйте при несовпадении.
Текст на реквизите	Пакет кофе на лайфстайл-снимке имел логотипоподобный знак и нечитаемый текст этикетки — даже при negative_prompt: "text, logo".	Не включайте в промпт реквизит с этикетками либо размывайте или обрезайте его. Никогда не допускайте поддельный текст в карточку товара.
Логика товара	На изображении сверху целые кофейные зёрна лежали внутри воронки.	Пусть лайфстайл-изображения проверяет человек, знакомый с этой категорией товаров.
Согласованность между изображениями	Рисунок рёбер и форма дна воронки различались на изображении товара, лайфстайл-снимке и снимке сверху.	Не смешивайте сгенерированные изображения «одного и того же» SKU на одной странице товара, если они не соответствуют реальному изделию.
Размеры и пропорции	Все результаты соответствовали требуемым пропорциям (1024², 1152×864, 720×1280).	Автоматически проверяйте размеры в пикселях после скачивания.

Последний пункт — ключевое решение для магазина. Используйте Imagen 4 для категорийных баннеров, атмосферных лайфстайл-изображений, рекламных креативов и заполнителей для товаров, которые существуют только в виде характеристик. Для фотографий в карточках, где должен быть показан именно ваш товар, начинайте с реальных фотографий продукта и переходите к модели генерации из изображения. Наше руководство по генерации из изображения для электронной коммерции на Seedream 4.5 подробно описывает этот процесс.

Часто задаваемые вопросы

Может ли imagen-4.0 поместить мой реальный товар в новую сцену? Нет. На HiAPI она принимает только prompt, aspect_ratio, negative_prompt и seed. Поля для входного изображения нет, поэтому использовать вашу фотографию товара как референс невозможно.

Удаляет ли negative_prompt весь текст? В наших тестах — нет. Отправлять его стоит, но на фоновом реквизите лайфстайл-снимков всё равно появлялся поддельный текст этикетки. Надёжное решение — избегать реквизита с этикетками.

Почему моя задача сразу завершается с TASK_FAILED? Сначала проверьте seed. Нецифровая строка вроде "sku-dripper-01" проходит валидацию, но в наших запусках каждая такая задача завершалась ошибкой. Используйте число в виде строки, например "1042".

Google-Imagen4 — это другая модель? В наших тестах запросы с "model": "Google-Imagen4" успешно выполнялись, а в полезной нагрузке задачи сообщалось "model": "imagen-4.0". В новом коде используйте imagen-4.0.

Дальнейшие шаги

Выберите товар, напишите для него три шаблона промптов из этой статьи и запустите пакетный скрипт для модели Imagen 4. Если вы подключаете это к конвейеру каталога, документация по асинхронному API описывает аутентификацию и опрос.