gpt-image-2.5-flare для карточек товаров в электронной коммерции: пакетный рабочий процесс на базе API hiapi

Съёмка товаров обычно — самый медленный этап подготовки каталога: каждый SKU нужно сфотографировать в студии, каждый сезонный фон — переснять, а каждое правило соотношения сторон платформы — учесть при очередной съёмке. gpt-image-2.5-flare на hiapi сводит большую часть этой работы к одному ID модели: он и генерирует изображения товаров по текстовому запросу, и редактирует существующие фотографии (заменяет фон, помещает в жизненные сцены, подгоняет размеры под разные каналы), не меняя сам товар. В этом руководстве мы покажем три реальных рабочих процесса с неотредактированным выводом API, а затем расскажем, как применять их пакетно ко всему каталогу, а не обрабатывать по одной картинке за раз.

Товары на изображениях ниже (зелёный стеклянный флакон с надписью «MOSS» и кобальтово-синий чайник с надписью «AER») — концептуальные предметы для демонстрации этой техники, а не реальная съёмка клиента, — но каждое изображение является реальным, неотредактированным выводом API hiapi, а не симуляцией.

Почему всё сводится к одному ID модели

gpt-image-2.5-flare выполняет две разные задачи в зависимости от того, что вы передаёте:

• Если опустить image_urls, он генерирует изображение только по вашему текстовому запросу (текст-в-изображение).
• Если добавить image_urls, он вместо этого редактирует переданные фотографии (изображение-в-изображение) — та же модель, тот же эндпоинт, та же цена.

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

• Уровни качества, а не единая фиксированная стоимость. Вы можете выбрать low / medium / high / xhigh / max для каждого запроса, поэтому пакет миниатюр на 500 SKU и десяток главных изображений для главной страницы не должны оплачиваться по одинаковой цене за штуку.
• Гибкие соотношения сторон. Для каждого запроса можно выбрать 1:1, 4:5, 9:16, 16:9 и другие пропорции, поэтому одну и ту же фотографию товара можно обрезать под квадратную сетку маркетплейса, вертикальную ленту мобильного приложения или широкий баннер без повторной съёмки.

Каждый вызов выполняется через асинхронный API задач hiapi: отправьте задачу в POST /v1/tasks, затем опрашивайте GET /v1/tasks/{id} (или используйте callback), пока статус не станет success. Синхронного вызова «изображение сразу в ответе» нет — генерация и редактирование занимают несколько секунд.

Шаг 1: создание чистой студийной фотографии с нуля

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

import os
import time
import requests

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


def create_task(prompt, quality="medium", aspect_ratio="1:1", image_urls=None, idempotency_key=None):
    payload = {"model": "gpt-image-2.5-flare",
               "input": {"prompt": prompt, "quality": quality, "aspect_ratio": aspect_ratio}}
    if image_urls:
        payload["input"]["image_urls"] = image_urls
    headers = dict(HEADERS)
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    resp = requests.post(BASE, headers=headers, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id, timeout_s=300, poll_every=5):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]  # download or re-upload immediately — it expires
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


studio_shot_url = wait_for_task(create_task(
    "Photorealistic square studio product photograph. Center exactly one translucent forest-green "
    "glass perfume bottle with a brushed silver cylindrical cap on a pale ivory stone pedestal. A "
    "small rectangular cream label reads \"MOSS\" in a thin serif font. Soft diffused studio lighting, "
    "seamless pale warm-gray background, subtle reflection, no props, no text elsewhere in frame.",
    quality="medium",
    aspect_ratio="1:1",
))

quality="medium" — разумное значение по умолчанию для первого прохода; все изображения в этой статье используют этот уровень. Повышайте отдельные SKU до high только тогда, когда дополнительная детализация оправдывает затраты (см. таблицу цен ниже).

Шаг 2: переработка фона без повторной генерации товара

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

seasonal_variant_url = wait_for_task(create_task(
    "Edit the supplied product photograph. Change ONLY the seamless background from pale warm gray "
    "to muted terracotta orange. Preserve the exact bottle shape and green glass color, the silver "
    "cap, the cream label and all its text, the lighting direction, and the camera angle exactly.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=[studio_shot_url],
))

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

В этом суть задачи «сезонное обновление» или «новая тема для рынка»: один вызов редактирования на SKU, товар не затронут, фон меняется. Запустите это 500 раз — и вы обновите тему всего каталога без повторной съёмки.

Шаг 3: размещение товара в жизненной сцене

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

lifestyle_url = wait_for_task(create_task(
    "Create a photorealistic square lifestyle product photograph using the supplied blue kettle as "
    "the exact product reference. Keep the original cobalt-blue kettle, black handle and base, "
    "brushed-metal spout and lid, black knob, and all lettering completely unchanged. Place it on a "
    "sunlit kitchen countertop with soft natural morning light, a few blurred kitchen props in the "
    "background, shallow depth of field.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=["<your kettle product photo URL>"],
))

Сохраняйте в каждом запросе редактирования ограничивающие формулировки («keep the original ... completely unchanged») — именно они не дают модели изменить товар, пока она меняет всё вокруг.

Пакетная автоматизация для полного каталога

Один вызов редактирования полезен; в масштабе каталога ценность в том, чтобы без присмотра запускать один и тот же подход для каждого SKU. Вот структура, которая хорошо работает в продакшене:

import concurrent.futures
import csv

QUALITY_BY_USE = {"thumbnail": "low", "listing": "medium", "hero": "high"}


def process_row(row):
    idem_key = f"{row['sku']}-{row['use']}-{row['background']}"
    prompt = (
        f"Edit the supplied product photograph. Change ONLY the seamless background to "
        f"{row['background']}. Preserve the exact product shape, color, materials, label text, "
        f"lighting direction, and camera angle."
    )
    try:
        task_id = create_task(
            prompt,
            quality=QUALITY_BY_USE[row["use"]],
            aspect_ratio=row["aspect_ratio"],
            image_urls=[row["source_photo_url"]],
            idempotency_key=idem_key,
        )
        return row["sku"], wait_for_task(task_id)
    except Exception as exc:
        return row["sku"], f"ERROR: {exc}"


with open("catalog.csv") as f:
    rows = list(csv.DictReader(f))  # sku,source_photo_url,background,use,aspect_ratio

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
    results = list(pool.map(process_row, rows))

При обработке более чем нескольких изображений важно следующее:

• Ключ идемпотентности для каждой строки. Отправляйте отдельный заголовок Idempotency-Key для каждого SKU/варианта, чтобы повторная попытка после таймаута не создавала — и не оплачивала повторно — дублирующие задачи.
• Ограничивайте параллелизм, не отправляйте всё сразу. Небольшой пул потоков (или асинхронный семафор) помогает избежать срабатывания ограничений скорости; при получении 429 делайте паузу и повторяйте попытку, а не считайте это фатальной ошибкой.
• Выбирайте уровень качества в зависимости от назначения изображения, а не по единому стандарту: для миниатюр и сеток обычно достаточно low/medium, а для главных изображений на главной странице или рекламных креативов стоит использовать high или xhigh.
• Получайте разные соотношения сторон из одного и того же отредактированного исходника, а не из оригинала: сначала выполните редактирование с заменой фона один раз, затем запросите из этого результата версии с обрезкой 1:1, 4:5 и 9:16, чтобы в каждом канале товар выглядел одинаково.
• Скачивайте или сразу перезагружайте URL вывода. Вывод задачи истекает; не используйте временный URL как постоянный источник изображений.

Цены

gpt-image-2.5-flare тарифицируется по количеству выходных изображений в зависимости от уровня качества — одинаковая ставка и для генерации с нуля, и для редактирования:

Качество	Цена за изображение
low	$0.0172
medium	$0.0672
high	$0.1829
xhigh	$0.3572
auto	$0.3572
max	$0.7143

На уровне medium смена темы каталога из 500 SKU с одним редактированием фона на товар обойдётся примерно в $33.60. Актуальную полную таблицу тарифов для всех моделей смотрите на странице цен.

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

Может ли редактирование случайно изменить мой товар? Ограничьте запрос редактирования одним изменением («изменить ТОЛЬКО фон…») и явно перечислите то, что должно остаться неизменным (форма, цвет, текст этикетки, угол камеры). Примеры выше показывают, что товар остаётся неизменным при каждом редактировании.

Может ли одна и та же модель и генерировать, и редактировать? Да — gpt-image-2.5-flare — это один ID модели. Если включить image_urls, он редактирует существующие фотографии; если опустить — генерирует только по запросу.

Сколько исходных изображений можно передать в одном вызове редактирования? Через image_urls можно передать до 16, хотя для большинства правок каталога товаров нужно только одно — то фото, которое вы хотите переработать.

Как избежать повторной оплаты при повторных попытках? Отправляйте уникальный заголовок Idempotency-Key для каждого запроса. Повторная попытка с тем же ключом вернёт исходную задачу, а не создаст новую.

Связанные материалы

Если вы настраиваете первый вызов, начните с руководства по API gpt-image-2.5-flare, чтобы получить минимальный рабочий пример и глубже разобраться в жизненном цикле асинхронной задачи. Дополнительные шаблоны запросов помимо съёмки товаров смотрите в GPT Image 2.5 Flare промпты: рецепты для копирования с реальными результатами. Полные параметры и схему смотрите на странице модели, а общие соглашения API (аутентификация, опрос задач, callback) — в документации hiapi.

Готовы попробовать на своём каталоге? Получите ключ API в панели hiapi и запустите приведённый выше пример студийной съёмки для своей первой фотографии товара.