HiAPI
Блог

Руководство по использованию

Генерация изображений товаров для электронной коммерции с помощью qwen-image-2.1-turbo через HiAPI API

Быстрый рабочий процесс визуализации каталога для разработчиков: прозрачный вывод PNG и работающий API-запрос

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

Где уместен qwen-image-2.1-turbo

Работа с изображениями для товарного каталога на первый взгляд кажется творческой задачей, но по сути это задача пропускной способности. Отдельное главное изображение можно доработать вручную, но магазину с тысячами SKU нужны единообразная композиция, предсказуемые сроки поставки и результаты, которые напрямую подключаются к существующему конвейеру ассетов. Выбранная вами модель изображений определяет, сколько элементов конвейера придётся перестраивать.

Обычно решающими являются три критерия:

  • Задержка под нагрузкой. Ночные задачи каталога относятся к пакетной обработке; модель, хорошо показывающая себя в интерактивных сценариях, всё равно может сделать обновление 10 000 SKU мучительно медленным.
  • Совместимость формата вывода. Если вашему этапу композитинга нужен альфа-канал, а модель возвращает только непрозрачные изображения, вам придётся добавить собственный шаг сегментации.
  • Поведение на языке описаний товаров. Товарные промпты короткие, конкретные и повторяющиеся — модель, стабильно справляющаяся с ними, лучше модели, которая отлично работает с открытыми художественными промптами.

Это руководство сосредоточено на первых двух критериях и шаблоне запроса, связывающем их. Мы рассмотрим место turbo-варианта в конвейере товарных изображений, то, как прозрачный вывод PNG меняет цепочку постобработки, и приведём запрос, который можно сразу поместить в worker. В конце обсудим, на что обращать внимание при масштабировании до пакетной обработки, и кратко сравним с подходом «изображение в изображение», когда генерация по тексту не подходит.

Задача товарных изображений ветвится по критериям выбора модели, что показано расходящимися ступенчатыми полосами.

Прозрачный вывод PNG и ваша цепочка постобработки

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

Когда это правильный первый выбор

Выбирайте qwen-image-2.1-turbo, если:

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

Когда нужна более мощная модель

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

Проектируйте сменный слот модели

Поскольку уровень turbo рассчитан на масштаб, имя модели следует рассматривать как конфигурацию, а не как жёстко заданную константу, разбросанную по кодовой базе. Чтение переменной окружения IMAGE_MODEL при запуске worker означает, что вы можете A/B-тестировать другую модель на части категорий без изменения кода запроса. Именно это решение делает остальное содержание руководства переносимым.

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

Работающий запрос к HiAPI для товарного изображения

Прозрачный PNG — это выбор вывода с наибольшим рычагом в конвейере каталога, потому что он переносит дорогостоящий шаг — отделение товара от фона — на этап генерации. Вместо того чтобы сегментировать непрозрачный рендер, вы получаете ассет с альфа-каналом и затем выполняете композитинг самостоятельно.

Что меняется дальше по потоку

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

На практике запланируйте следующие шаги:

  • Проверьте альфа-канал. Убедитесь, что изображение действительно имеет нетривиальный альфа-канал и что объект не обрезан по краям кадра. Вырезка, касающаяся границы, — это сбой генерации, а не проблема композитинга.
  • Нормализуйте холст. Перед композитингом измените размер и дополните вырезку на согласованном холсте, чтобы положение разных SKU было предсказуемым.
  • Выполняйте композитинг отдельно для каждого места публикации. Храните предустановки фона как данные (размер, цвет, необязательные фоновые ассеты) и рендерите каждое место публикации из одного и того же исходного PNG.
  • Храните исходник, публикуйте рендеры. Сохраняйте прозрачный оригинал как канонический ассет, а каждый композитный вариант рассматривайте как производный артефакт, который можно перегенерировать.

Учитывайте компромисс по размеру файла: альфа-канал увеличивает PNG, а хранилище каталога умножает это на каждый вариант. Если ваш CDN поддерживает WebP или AVIF, конвертируйте при публикации, сохраняя исходный PNG.

Прозрачная вырезка как плавающий слой: один и тот же силуэт накладывается на каждый вариант фона, а затем справа переходит к этапу хранения.

Масштабирование до пакетных задач и избегание ловушек интеграции

Всё нижеописанное работает через унифицированный интерфейс HiAPI — один базовый URL, одни учётные данные, единообразная форма запроса для разных моделей. Прежде чем фиксировать схему, получите точный список параметров и актуальные имена полей на странице модели qwen-image-2.1-turbo; здесь важно сам шаблон.

Форма запроса

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

import os, requests

HIAPI_KEY = os.environ["HIAPI_API_KEY"]
MODEL = os.environ.get("IMAGE_MODEL", "qwen-image-2.1-turbo")

def product_prompt(sku):
    return (
        f"studio product photo of {sku['name']}, {sku['material']}, "
        f"{sku['color']} finish, three-quarter view, soft even lighting, "
        "centered on a plain background, no text, no props"
    )

def generate(sku):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {HIAPI_KEY}"},
        json={
            "model": MODEL,
            "prompt": product_prompt(sku),
            "transparent_background": True,
            "n": 1,
        },
        timeout=120,
    )
    resp.raise_for_status()
    return resp.json()

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

Обрабатывайте ответ защитно

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

Сравнение с путём «изображение в изображение»

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

Шаблонизируйте промпты как данные

Храните фрагменты промптов по категориям в файлах конфигурации, а не в коде. Каждый SKU предоставляет слоты; категория предоставляет каркас предложения и негативные ограничения ("no text, no watermarks, no props"). Когда композиция категории неверна, вы исправляете один шаблон, а не тысячи строк данных.

Повторяйте с целью

Отделяйте повторяемые сбои (таймауты, временные ошибки сервера, ограничения скорости) от терминальных сбоев (неверные параметры, отклонённые промпты). Для первого типа используйте экспоненциальную задержку и верхний предел повторов; для второго — немедленно завершайте сбоем и раскрывайте причину, потому что повтор некорректного запроса только расходует очередь. Здесь важна идемпотентность — используйте SKU плюс хеш промпта в качестве ключа каждой задачи, чтобы повторная задача перезаписывала, а не дублировала.

Проверяйте до появления в витрине

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

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

Отправляйте не прошедшее контрольный этап в очередь проверки, а не просто отбрасывайте. Тихие сбои — именно так каталог незаметно наполняется товарами неверного цвета.

Учитывайте ограничения параллелизма

Пакетные задачи часто достигают ограничений скорости всплесками, а не постепенно. Установите параллелизм worker ниже предполагаемого предела, сделайте этот предел настраиваемым и позвольте очереди поглощать накопление. Конвейер, который упирается в ограничение, но завершает работу, лучше конвейера, который колеблется туда-сюда.

Бюджетируйте по выводу, а не по запросу

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

Сравнение с путём «изображение в изображение»

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

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

Для большинства каталогов практичное разделение таково:

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

Оба варианта используют один и тот же каркас конвейера, поэтому переключение — это просто идентификатор модели плюс поле ввода, а не переписывание. Когда вам нужен вывод на основе референсных изображений, модель «изображение в изображение» qwen-image-3.0 подключается к тому же worker — достаточно приложить референсное изображение рядом с промптом.

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

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API