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

Каталог товаров для электронной коммерции держится на единообразии. Продавцу с 40 SKU не нужно 40 разных съёмок — ему нужен один привлекательный фон и способ быстро поместить на него каждый товар. Именно для этого и существует редактирование изображений по референсу, и именно в этом силён grok-imagine/image-to-image на hiapi API: дайте ему сцену и фото товара, и он скомпонует их в чистое изображение, соответствующее бренду, — без ручных масок и без отдельного шага вырезания.

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

Что на самом деле делает модель

grok-imagine/image-to-image принимает текстовый промпт и несколько референсных изображений и объединяет их в новое изображение. Для фотографии товаров это означает:

• Единый фон — каждая фотография SKU ставится на одну и ту же стилизованную сцену (стол, полку, студийный задник), и ничего не нужно переснимать.
• Сценовую композицию — вырезанный товар объединяется с референсом окружения, чтобы свет и композиция совпадали.
• Перенос стиля между референсами — цветокоррекцию или реквизит с одного изображения переносят на другое, при этом сам товар остаётся без изменений.

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

Реальная схема (проверена на живом API, а не по странице с тарифами)

Мы напрямую опросили POST /v1/tasks с помощью grok-imagine/image-to-image, и схема входных данных этой модели принимает ровно два поля:

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "string, required",
    "image_urls": ["array of public image URLs, required, max 3"]
  }
}

Вот и всё — ни resolution, ни aspect_ratio, ни параметра strength. Любое другое содержимое в payload будет отклонено строгой схемой.

Стоит указать на одно расхождение, которое требует исправления: страница тарифов hiapi в настоящее время утверждает, что модель поддерживает «до 6» референсных изображений. Мы протестировали это напрямую, отправив 6 и 7 URL изображений в одном запросе, и оба варианта были отклонены:

{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 6, want 3"}
{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 7, want 3"}

На момент написания действующее ограничение — 3 изображения на вызов, а не 6. Если вы строите конвейер вокруг этой модели, рассчитывайте на 3 и считайте любой маркетинговый текст, утверждающий иное, устаревшим — перед запуском автоматизации, зависящей от этого ограничения, обязательно подтвердите его живым вызовом POST /v1/tasks, поскольку эти ограничения меняются по мере развития платформы.

Автоматическое соотношение сторон: формат вывода следует за вашим первым референсным изображением

У модели нет входного поля aspect_ratio, так откуда же берётся форма вывода? Мы провели контролируемый тест, чтобы выяснить это: одинаковый промпт, одинаковые два референсных изображения, менялся только порядок в image_urls.

В этом рендере фотография товара (рюкзак) была указана первой в image_urls, а за ней следовала фоновая сцена. Вывод вернулся размером 1248×832 — горизонтальное изображение 3:2, совпадающее с пропорциями фотографии товара.

Тот же промпт, те же два изображения — но на этот раз фоновая сцена была указана первой. Вывод вернулся размером 1024×1024 — квадратный кроп, совпадающий с соотношением сторон референса сцены, а не товара.

Правило таково: соотношение сторон вывода grok-imagine/image-to-image наследуется от первого URL в image_urls. Оно не считывает подсказки о композиции из вашего промпта («фото товара» или «широкая сцена») — оно чисто позиционное. Как только вы это знаете, это становится действительно полезным рычагом: чтобы получить кроп, предпочитаемый конкретной торговой площадкой, достаточно переставить элементы массива референсов. Для квадратных карточек товара в стиле Instagram поставьте квадратный референс первым; для широких баннеров — горизонтальный.

Цены (сверено с живым прайс-листом)

Модель	Тип вызова	Цена
grok-imagine/text-to-image	Текст → изображение	$0.03 / изображение
grok-imagine/image-to-image	Редактирование по референсу (это руководство)	$0.03 / изображение + $0.003 за каждое референсное изображение
grok-imagine-quality/text-to-image	Текст → изображение, премиальный уровень	$0.07 / изображение (1K)
grok-imagine-quality/image-to-image	Редактирование по референсу, премиальный уровень	$0.08 / изображение (1K), $0.10 / изображение (2K), + $0.015 за каждое референсное изображение

Базовый уровень grok-imagine/image-to-image, используемый в этом руководстве, не зависит от разрешения и оплачивается по единому тарифу — вы не платите надбавку за 2K/4K, как на уровне -quality. Для обновления каталога, где десятки SKU компонуются на одной сцене, цифра для бюджета — $0.036 за изображение (одно фото товара плюс один референс сцены). Перед массовыми прогонами обязательно перепроверьте /en/pricing, поскольку тарифы могут меняться.

Если вам нужны более резкие детали на каждом изображении и вы готовы к росту цены примерно в 3 раза, уровень grok-imagine-quality — это более точная версия того же рабочего процесса. Для чистой генерации изображений товаров из текста без каких-либо референсных фотографий см. разбор text-to-image на базовом уровне.

Пакетный скрипт: одна сцена, весь каталог

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

import os
import time
import requests

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

SCENE_URL = "https://static.hiapi.ai/blog/grok-imagine-image-to-image-ecommerce/scene-base.jpg"
PROMPT = (
    "Composite the product from the first reference photo naturally into the "
    "second reference's studio scene, matching its lighting and shadow direction. "
    "Keep the product's shape, color, and texture unchanged."
)


def submit(product_url: str) -> str:
    payload = {
        "model": "grok-imagine/image-to-image",
        "input": {
            "prompt": PROMPT,
            "image_urls": [product_url, SCENE_URL],  # product first -> output follows its ratio
        },
    }
    resp = requests.post(f"{API_BASE}/tasks", headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


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


if __name__ == "__main__":
    product_urls = [
        "https://your-storage.example.com/catalog/dripper-raw.jpg",
        "https://your-storage.example.com/catalog/sneaker-raw.jpg",
        "https://your-storage.example.com/catalog/backpack-raw.jpg",
    ]
    for url in product_urls:
        task_id = submit(url)
        output_url = wait_for_result(task_id)
        print(f"{url} -> {output_url}")

Для производственных конвейеров зарегистрируйте на задаче callback.url вместо опроса в цикле — полную структуру payload обратного вызова см. в каталоге моделей hiapi. Сохраняйте taskId вместе с SKU вашего товара, чтобы неудачные задачи можно было повторить без повторной отправки всей партии.

Примеры с реальными фотографиями товаров

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

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

Можно ли использовать более 3 референсных изображений за один вызов? Нет. Живая схема накладывает на image_urls ограничение maxItems: 3 — это подтверждено прямым тестированием API, независимо от того, что говорится в маркетинговых текстах в других местах. Стройте промпты с учётом не более 3 референсов (обычно: товар + сцена или товар + сцена + стилевой референс).

Как контролировать соотношение сторон вывода? У модели нет параметра aspect_ratio. Вывод наследует соотношение сторон первого изображения в image_urls — переставляйте референсы, чтобы получить нужные пропорции.

Поддерживает ли она генерацию только из текста без референсов? Нет — image_urls является обязательным полем. Для чистой генерации изображений товаров из текста используйте grok-imagine/text-to-image по цене $0.03 за изображение.

Есть ли у модели версия с более высокой точностью? Да, grok-imagine-quality/image-to-image выполняет тот же рабочий процесс по референсу за $0.08 за изображение (1K) или $0.10 за изображение (2K), плюс $0.015 за каждое референсное изображение, обеспечивая более резкие детали.

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

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