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

Большинство конвейеров обработки изображений товаров ломаются, как только возникает следующая потребность: нужно из одного и того же фото получить три разных формата — квадратное изображение для сетки каталога, вертикальный кроп для страницы товара (PDP) на мобильном и широкое изображение для главного баннера на главной странице. Перекроп одного ключевого изображения редко выглядит хорошо во всех пропорциях — либо товар обрезается, либо появляются нелепые пустые области. grok-imagine/text-to-image обходит эту проблему: он может генерировать нативно в нужном вам соотношении, включая два широких формата, созданных специально для таких баннерных задач (2:1 и 20:9), с единой ценой $0.03 за изображение в API hiapi независимо от разрешения.

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

Ценовое позиционирование

Проверено по странице цен hiapi на момент написания:

Модель	Цена за изображение	Разрешение	Управление соотношением сторон
grok-imagine/text-to-image	Единая $0.03	1K или 2K, одна цена	13 соотношений, включая 2:1, 20:9
grok-imagine-quality/text-to-image	$0.07 (1K) / $0.10 (2K)	Цена зависит от разрешения	Тот же набор соотношений

Качественный уровень действительно заметно улучшает мелкие детали — блики, текстуру ткани, мелкий текст — и для небольшого числа действительно ключевых изображений стоит доплаты. Для большей части изображений каталога (миниатюры сетки, вариации в интерьере, другие ракурсы) базовой модели вполне достаточно, и разница в цене в 2-3 раза при пакетной обработке не оправдана.

Работающий запрос

Все изображения на этой странице получены с одной конечной точки:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "matte ceramic pour-over coffee dripper on a pale oak table, soft morning window light from the left, small negative space top-right, no text, no logo, product photography",
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }
  }'

Это возвращает taskId; опрашивайте GET /v1/tasks/{taskId}, пока status не станет success, затем получите output[0].url и скачайте — этот URL подписан и истекает, поэтому байты следует сохранить сразу, а не ссылаться на него напрямую.

Во время тестирования нас подставили три детали схемы, о которых стоит знать до того, как вы начнёте строить своё:

• aspect_ratio — строгий перечень из 13 значений, не свободный формат. Отправка любого другого значения возвращает 400 с полным списком: 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2. Два соотношения, нужные для баннеров, — это 2:1 и 20:9 — большинство моделей изображений на hiapi достигают максимум 21:9 или вовсе не предлагают сверхширокие опции.
• resolution — только строчными буквами — используйте "2k", а не "2K". Отправка заглавных букв отклоняется напрямую, а не преобразуется молча.
• Схема ввода строгая. Лишние или с ошибками в написании поля (оставшийся negative_prompt, ключ style, скопированный из примеров других моделей) приводят к отказу всего запроса, а не игнорируются.

Написание промптов для чистых изображений уровня каталога

Главный рычаг для получения последовательных результатов каталога — явно указать, чего вы не хотите. Для приведённого выше ключевого изображения на белом фоне работающий промпт такой:

"Матовый керамический кофейный пуровер (воронка) на чистом бесшовном белом фоне, студийное освещение софтбоксом, по центру, без градиентов теней, кроме мягкой контактной тени, без текста, без водяных знаков, без реквизита, фотография товара для электронной коммерции, резкий фокус"

Для вариаций в интерьере, используемых для вторичных изображений PDP или баннеров для писем, замените фон и подсказки по освещению, но сохраните ту же дисциплину «без текста / без водяных знаков / без дополнительного реквизита, кроме указанного» — именно это мешает grok-imagine добавлять беспорядочные объекты на сам товар или нечитаемый текст этикеток:

"Та же керамическая кофейная воронка на деревянной кухонной стойке, рядом кружка с паром, тёплый утренний свет, малая глубина резкости, уютный домашний кухонный фон в мягком размытии, без текста, без логотипа"

Рабочий процесс для сверхшироких баннеров

Когда нужен баннер для главной страницы или категории, а не миниатюра каталога, 2:1 и 20:9 — именно те два соотношения, которые делают grok-imagine особенно ценным. Приём — явно задать негативное пространство в промпте, а не надеяться на то, что кроп случайно подойдёт — опишите, где в кадре находится товар и какие области должны оставаться пустыми:

"Матовая керамическая кофейная воронка в правой трети кадра, свет золотого часа на открытом воздухе, просторное пустое негативное пространство в левых двух третях изображения для наложения текста заголовка, кинематографичная широкая композиция, без текста, без логотипа"

{
  "model": "grok-imagine/text-to-image",
  "input": {
    "prompt": "matte ceramic pour-over coffee dripper positioned in the right third of frame, golden-hour outdoor light, generous empty negative space across the left two-thirds of the image for headline text overlay, cinematic wide composition, no text, no logo",
    "aspect_ratio": "20:9",
    "resolution": "2k"
  }
}

Если вашей CMS нужны точные размеры в пикселях, а не соотношение, генерируйте в ближайшем поддерживаемом соотношении, а затем обрезайте без потерь из этого изображения — конкретные расчёты заполнения см. в нашем руководстве по точным размерам через API.

Пакетная генерация полного списка кадров

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

import os
import time
import requests

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

SHOTS = [
    {
        "name": "hero",
        "prompt": "matte ceramic pour-over coffee dripper on a pure white seamless "
                  "background, studio softbox lighting, centered, e-commerce product "
                  "photography, no text, no watermark",
        "aspect_ratio": "1:1",
    },
    {
        "name": "lifestyle",
        "prompt": "same ceramic pour-over dripper on a wooden kitchen counter next to "
                  "a steaming mug, warm morning light, shallow depth of field, no text",
        "aspect_ratio": "4:3",
    },
    {
        "name": "banner",
        "prompt": "ceramic pour-over dripper in the right third of frame, soft studio "
                  "light, empty negative space across the left two-thirds for headline "
                  "text, no text, no logo",
        "aspect_ratio": "2:1",
    },
]


def create_task(shot):
    payload = {
        "model": "grok-imagine/text-to-image",
        "input": {"prompt": shot["prompt"], "aspect_ratio": shot["aspect_ratio"], "resolution": "2k"},
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id, poll_interval=5, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


for shot in SHOTS:
    task_id = create_task(shot)
    url = wait_for_result(task_id)
    image_bytes = requests.get(url, timeout=120).content
    with open(f"{shot['name']}.jpg", "wb") as f:
        f.write(image_bytes)
    print(f"{shot['name']}: saved {len(image_bytes)} bytes")

Если вы запускаете полный пакет из нескольких SKU, отправьте все три задачи сразу, а затем опрашивайте их одновременно (небольшой asyncio или пул потоков подойдёт) — каждая задача обычно завершается в течение минуты, а последовательный запуск лишь зря добавляет время простоя.

Стоимость реального запуска по каталогу

При единой цене $0.03 за изображение приведённый выше набор из трёх изображений (ключевое + интерьер + баннер) стоит $0.09 за SKU. При масштабировании:

• 50 SKU × 3 изображения = 150 изображений → $4.50
• 500 SKU × 3 изображения = 1 500 изображений → $45
• Если добавить апгрейд до grok-imagine-quality только для ключевых изображений 2K ($0.10 вместо $0.03), итог для 500 SKU составит $80 — всё ещё мизерная доля по сравнению с одной традиционной фотосессией товаров.

Сравнение grok-imagine с остальной линейкой

Если изображение должно ожить — например, 6-секундный динамичный ролик товара для соцрекламы вместо статичного баннера — та же серия покрывается через grok-imagine-image-to-video, который использует одно из этих статичных изображений в качестве начального кадра; этот рабочий процесс мы описали отдельно в руководстве по коротким видео. Для команд, сравнивающих с конвейером каталога на базе Nano-Banana, наше руководство по Nano-Banana для электронной коммерции — ближайший ориентир для сравнения: та же структура API задач, разные сильные стороны моделей.

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

Поддерживает ли grok-imagine/text-to-image референсное изображение (i2i), а не только текстовые промпты? Да — но это отдельный вариант модели (grok-imagine/image-to-image) со своей схемой ввода. Это руководство охватывает путь только текст-в-изображение.

Почему мой запрос возвращает 400 с ошибкой «additional properties»? Схема ввода строгая. Внимательно проверьте, что вы отправляете только prompt, aspect_ratio и, опционально, resolution — не переносите дополнительные поля, скопированные из примеров других моделей.

Можно ли получить точное соотношение, например 1200×630, вместо выбора из перечня? Генерируйте в ближайшем поддерживаемом соотношении (16:9 близко ко многим форматам веб-баннеров), а затем обрезайте без потерь на постобработке — конкретный метод заполнения см. в руководстве по точным размерам, ссылка выше.

Стоит ли ждать 2K-разрешение по сравнению с 1K? Для этой модели обе разрешения стоят одинаково, поэтому по умолчанию используйте 2K, если у вас нет жёсткого бюджета задержки — больше деталей бесплатно.

Попробуйте сами

Весь доступ к API здесь доступен через стандартный ключ hiapi — см. документацию для аутентификации и полного справочника по опросу задач, а перед запуском пакетной обработки ознакомьтесь со страницей цен, чтобы узнать актуальные тарифы по всей линейке моделей.