Создание изображений товаров для электронной коммерции с помощью z-image через API hiapi

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

z-image — это модель генерации изображений по тексту уровня Turbo на hiapi, созданная именно для этой ниши: быстрое создание фотореалистичных изображений, точный текст на изображении (английский и китайский), цена — $0.008 за изображение, что меньше трети цены большинства альтернатив. Каждое изображение в этом руководстве сгенерировано с помощью точно такого же промпта, который показан рядом с ним, через тот же вызов /v1/tasks, который вы скопируете ниже; каждая генерация занимает примерно 30–60 секунд от начала до конца.

Почему для изображений товаров стоит выбрать z-image

Для конвейера электронной коммерции важны три свойства, и z-image хорошо справляется со всеми тремя:

• Рендеринг текста. При соблюдении приведённых ниже правил составления промптов промо-карточки, логистические баннеры и этикетки на бутылках возвращаются с правильно написанными словами.
• Скорость. Это модель, настроенная на Turbo; наши тестовые генерации каждый раз завершались намного быстрее минуты, что позволяет обработать сотни изображений SKU за время одной чашки кофе.
• Цена. При $0.008 за изображение (проверено на странице цен) обновление каталога из 1000 изображений стоит $8. Та же задача на gpt-image-2 ($0.03 за изображение) обойдётся в $30.

Если вам нужен более полный обзор модели — настройка ключей, общие примеры, когда её не стоит использовать — см. Z-Image API: цены, API-ключи, примеры и области применения. Это руководство посвящено рабочему процессу электронной коммерции.

Проверенный интерфейс API

z-image работает на асинхронной конечной точке задач hiapi. Вы отправляете задачу, опрашиваете её до успешного завершения, затем скачиваете результат. Мы подтвердили два факта о схеме на работающем API (оба отличаются от некоторых других моделей на платформе):

1. input принимает только prompt и aspect_ratio. Отправка поля resolution возвращает HTTP 400 (additional properties not allowed) — в отличие от gpt-image-2, где это поле обязательно.
2. aspect_ratio должен быть одним из 1:1, 4:3, 3:4, 16:9, 9:16. Любое другое значение (мы пробовали 3:2) отклоняется с кодом 400 и перечислением допустимых значений.

Выходное разрешение фиксировано пропорционально — наши результаты возвращались в PNG: 1536×1536 (1:1), 1344×768 (16:9), 928×1232 (3:4) и 1728×1296 (4:3).

Отправка задачи

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "Studio e-commerce product photo: a matte black insulated steel water bottle on a seamless light-gray background...",
      "aspect_ratio": "1:1"
    }
  }'

Ответ содержит идентификатор задачи:

{"code": 200, "data": {"taskId": "tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG"}}

Опрос и скачивание

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

Опрашивайте каждые несколько секунд, пока data.status не станет success и не появится data.output; считайте fail конечным состоянием. Полезный совет: вскоре после генерации задача может кратковременно сообщать промежуточный статус (мы наблюдали archiving), прежде чем появится массив output, поэтому ваш цикл должен проверять наличие URL вывода, а не только строку статуса.

import os, time, requests

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

def generate(prompt: str, ratio: str = "1:1") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "z-image",
        "input": {"prompt": prompt, "aspect_ratio": ratio},
    }, timeout=60)
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        output = task.get("output") or []
        if output and output[0].get("url"):
            return requests.get(output[0]["url"], timeout=120).content
        if task.get("status") == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...your product prompt...", "1:1")
open("product.png", "wb").write(png)

Скачивайте сразу. output[0].url — это временная ссылка с отметкой expireAt: сразу после успешного завершения задачи сохраните байты в собственное хранилище (S3/R2/CDN). Если задача кажется зависшей, здесь описано, как диагностировать зависшие или просроченные задачи hiapi.

Пять рецептов для электронной коммерции с реальными результатами

Все изображения ниже — реальные результаты генерации z-image по точно таким же промптам, которые показаны. Без какой-либо ретуши.

1. Главное изображение с ценником

Studio e-commerce product photo: a matte black insulated steel water bottle centered
on a seamless light-gray background with soft shadow. A rectangular coral paper card
leans against the bottle. The card contains ONLY these two lines of bold clean
sans-serif text and no other words: "SUMMER SALE" on line one, "$19.99" on line two.
Text flat-on to camera, large, perfectly legible. Photorealistic.

Обратите внимание на формулировку: отображаемый текст заключён в кавычки, а в промпте сказано, что карточка содержит только эти слова. В первой попытке мы описали текст встроенно («...reads exactly: SUMMER SALE on the first line and $19.99 on the second line»), и модель добросовестно набрала слово «ON» между двумя строками — слова инструкции просочились в результат. Заключайте буквальные строки в кавычки; инструкции держите вне кавычек.

2. Широкий промо-баннер

Wide e-commerce promo banner, photorealistic flat-lay of white sneakers and a kraft
shipping box on a pastel blue background. On the right side, bold navy sans-serif
text with exactly these four words and amount, nothing else: "FREE SHIPPING OVER $50".
All four words must appear. Text large, straight, perfectly legible. Clean commercial
studio lighting.

16:9 даёт баннер размером 1344×768, который можно сразу разместить в главном визуальном блоке главной страницы магазина.

3. Вертикальная карточка скидки для соцсетей

Vertical social-media product card: a small brown glass cosmetic dropper bottle on a
warm beige podium, soft daylight. Above the bottle, bold black modern sans-serif
headline text reads exactly: 30% OFF TODAY ONLY. Text flat to camera, large and
perfectly legible. Minimalist premium e-commerce style, photorealistic.

3:4 (928×1232) — наиболее близкий к формату поста в ленте; при необходимости платформы обрежьте ниже по конвейеру до 4:5.

4. Читаемая этикетка на упаковке

Macro e-commerce product photo of a frosted glass skincare bottle with a clean white
label. The label text, printed in elegant dark sans-serif, reads exactly: GLOW SERUM
on the first line and VITAMIN C 10% on the second line. Straight-on angle, label
fully visible and sharp, soft studio lighting, photorealistic, white background.

Это самый сложный тест в подборке — мелкий текст на изогнутом стекле — этикетка вернулась чистой, включая «10%».

5. Цветовая линейка (без текста)

E-commerce catalog photo: three identical ceramic coffee mugs lined up left to right
in sage green, terracotta orange, and navy blue, on a plain white studio background
with soft even shadows. No text anywhere in the image. Photorealistic, consistent
product geometry across all three mugs.

Согласованная геометрия между вариантами — именно то, что делает изображение пригодным для полосы каталога: z-image сохранил одинаковую форму всех трёх цветных кружек за одну генерацию.

Правила промптов, благодаря которым текст выживает

Сжато из того, что работало (и не работало) в наших реальных запусках:

1. Заключайте буквальные строки в кавычки. text reads exactly: "SUMMER SALE" — модель рассматривает слова вокруг без кавычек как возможный текст для отображения.
2. Добавляйте «and no other words» (и никаких других слов). Иначе модель может выдумать дополнительный текст на бейджах, чтобы заполнить пространство.
3. Держите текст прямо перед камерой. Наша единственная генерация с искажёнными буквами была на бирке с текстом под углом; тот же текст на плоской карточке вышел безупречно. Перспективные искажения — первое место, где ломаются глифы.
4. Один-два текстовых блока на изображение. Каждый дополнительный текстовый блок умножает вероятность сбоя; сложные макеты компонуйте ниже по конвейеру.
5. Проверяйте перед публикацией. При такой цене вы можете позволить себе цикл повторных попыток: сгенерируйте, распознайте текст через OCR или проверьте глазами, при несовпадении сгенерируйте заново. Даже с одной повторной попыткой на каждое неудачное изображение стоимость остаётся малой долей от альтернативной модели.

Стоимость пакетной обработки

Конкретный сценарий: 200 SKU × 3 материала на каждый (изображение для карточки товара, промо-баннер, карточка для соцсетей) = 600 изображений.

Модель	Цена за изображение	600 изображений	Примечания
z-image	$0.008	$4.80	Скорость Turbo, сильный рендеринг текста на изображении
flux-schnell	$0.005	$3.00	Самая дешёвая, но не ориентирована на рендеринг текста
qwen-image-2.0	$0.025	$15.00	Сильное общее качество
gpt-image-2	$0.03	$18.00	Требует поля resolution; руководство по электронной коммерции см. здесь

(Цены взяты со страницы цен hiapi на момент публикации.)

Пакетный режим — это просто помещение функции generate() выше в цикл: отправьте несколько задач параллельно, соберите идентификаторы задач, затем опрашивайте их группами. Если вы собираетесь сильно наращивать объёмы, сначала прочитайте как hiapi обрабатывает ограничения скорости и всплески трафика.

Начало работы

Получите API-ключ в вашей консоли, затем направьте приведённые выше фрагменты кода на собственный каталог товаров — страница модели z-image содержит карточку модели, а документация hiapi подробно описывает Task API. При $0.008 за генерацию самый дешёвый способ понять, подходит ли это для вашего конвейера, — прогнать сегодня после обеда ваши десять самых сложных SKU.