HiAPI
Блог

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

muse-image-1.0/text-to-image для изображений товаров электронной коммерции: руководство по рабочему процессу разработчика

Шаблоны промптов для ракурсов и освещения, выбор размеров и пакетные запросы через API HiAPI

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

Почему text-to-image подходит для рабочих нагрузок с товарами электронной коммерции

Работа с каталогом по своей сути повторяющаяся: один и тот же товар, снятый с нескольких ракурсов, при одном и том же освещении, на одном и том же фоне, в нескольких размерах. Именно эта повторяемость — то, с чем модели text-to-image справляются хорошо: не заменяя студийную съёмку флагманских товаров, а дешёвым и единообразным способом заполняя длинный хвост каталога.

Сценарии, где генерация действительно полезна:

  • Крупные партии вариантов. Цветовые схемы, незначительные различия SKU и изменения упаковки — случаи, когда стоимость пересъёмки превышает ценность самого изображения.
  • Заглушки и материалы до запуска. Страницы листингов, материалы для внутренних обзоров и A/B-тесты нуждаются в правдоподобном контенте до того, как будут готовы финальные фотографии.
  • Исследование композиции. Попробовать съёмку сверху в стиле флэтлей и главное изображение под углом 45 градусов, прежде чем задействовать фотографа и студию.

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

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

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

Вызов muse-image-1.0/text-to-image через HiAPI

Все запросы идут через один интерфейс HiAPI, поэтому вы аутентифицируетесь один раз и сохраняете одного клиента для всех вызываемых моделей. Идентификатор модели — muse-image-1.0/text-to-image; ваш запрос несёт промпт, выбранный выходной размер и любые параметры одной генерации, которые вы хотите зафиксировать.

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

  1. Храните промпт в переменной, а не встраивайте его в запрос. Вы будете переиспользовать и сравнивать его сотни раз.
  2. Записывайте точный отрендеренный промпт для каждого вывода. Когда через три недели изображения будут выглядеть неправильно, промпт — ваша единственная опора для отладки.
import os
from hiapi import HiAPI

client = HiAPI(api_key=os.environ["HIAPI_API_KEY"])

prompt = render_product_prompt(product, angle="three-quarter", light="softbox-left")

result = client.images.generate(
    model="muse-image-1.0/text-to-image",
    prompt=prompt,
    size="1024x1024",
)

save_asset(product_id=product.id, angle="three-quarter", result=result)

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

Запрос проходит от клиента через эндпоинт к модели, а плетёные ленты возвращают результат-изображение.

Шаблоны промптов для единообразных ракурсов съёмки

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

Рабочий каркас:

{subject_block}. {camera_block}. {light_block}. {background_block}. {style_block}

Меняется только subject_block в зависимости от товара. camera_block — константа для каждого ракурса:

  • Главное изображение / вид в три четверти: product photographed at a 45-degree three-quarter view, slightly above eye level, full product in frame with even margins
  • Фронтальный вид: straight-on front view, camera at product mid-height, centered, no perspective tilt
  • Флэтлей сверху: directly overhead top-down view, product centered, flat lay composition
  • Крупный план деталей: close-up macro view of the product surface, shallow depth of field

Два правила делают это работающим на практике:

  • Указывайте ракурс дважды. Явный угол плюс формулировка о композиции (например, "full product in frame with even margins") надёжнее, чем любое из них по отдельности.
  • Избегайте относительных ссылок. "Same angle as the last image" ничего не значит для модели text-to-image; каждый промпт должен существовать самостоятельно.

Храните шаблоны в системе контроля версий вместе с кодом рендеринга. Когда вы меняете camera_block, повышайте версию и перед коммитом перегенерируйте небольшую выборку — изменение формулировки означает изменение всего каталога.

Шаблоны промптов для освещения и фона

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

Язык освещения, который надёжно переносится:

  • Направление: key light from camera left, light from upper right, soft overhead light. Направление — самый наглядный рычаг единообразия — зафиксируйте его для каждого типа съёмки.
  • Качество: soft diffused light, large softbox, gentle shadows, hard directional light with defined shadow edge.
  • Заполняющий свет и блики: subtle fill from the right, low-contrast shadows, clean highlight on the top surface.

Язык фона:

  • Бесшовная студия: on a seamless light grey studio backdrop, no horizon line, soft contact shadow beneath the product.
  • Лайфстайл-поверхность: resting on a matte stone surface, softly out-of-focus neutral background.
  • Удобно для вырезания: isolated on a plain white background, product fully in frame, generous margins for cropping.

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

Выбор выходных размеров и соотношений сторон

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

  • Сетки и плитки категорий: квадрат. Обрезка в сетке товаров непредсказуема, поэтому квадратная композиция с достаточными полями помещается в большинство макетов плиток.
  • Страницы с описанием товара: квадрат или 4:3 — ориентируйтесь на размер просмотрщика с масштабированием, а не на миниатюру. Если страница товара обрезается до фиксированного соотношения, точно его соблюдайте и не боритесь с ним в CSS.
  • Баннеры и полосы главных изображений: широкоформатные, с явно запланированной безопасной зоной. Требуйте центрирования товара и негативного пространства по бокам, чтобы было куда разместить маркетинговый текст.
  • Email и социальные сети: соблюдайте нативные пропорции платформы; перегенерировать дешевле, чем добавлять поля.

Несколько эмпирических правил:

  1. Выберите один канонический размер на каждое место размещения и переиспользуйте его. Смешивание размеров в одной сетке плиток даёт заметные различия в качестве.
  2. Не увеличивайте сгенерированные изображения, чтобы заполнить более крупное место. Генерируйте больший размер и уменьшайте.
  3. Проверяйте композицию заново после изменения пропорций. Главное изображение под 45 градусов, скомпонованное для квадрата, может потерять основание товара при широкоформатной обрезке; соответствующим образом скорректируйте формулировку о композиции в camera_block.
  4. Сохраняйте размер в записи задачи. При последующей проверке выходных данных размер — часть контекста, а не шум в метаданных.

Пакетные запросы и обработка результатов по элементам

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

Надёжный цикл делает четыре вещи:

  • Детерминированно рендерит промпт: из шаблона и полей товара, и сохраняет отрендеренную строку в задаче.
  • Ограничивает параллелизм: до объёма, который выдерживают ваш аккаунт и нижележащее хранилище; не запускайте весь каталог разом.
  • Обрабатывает результаты по элементам. Пакетные операции успешны или неуспешны по элементам, поэтому записывайте каждый результат под его job_id и никогда не предполагайте атомарности всего пакета.
  • Повторяет с экспоненциальной задержкой только при временных ошибках. Ошибки валидации — некорректный промпт, неподдерживаемый размер — при повторе провалятся так же, поэтому сначала классифицируйте, потом повторяйте.
for job in queue.fetch_pending(limit=50):
    try:
        result = client.images.generate(
            model="muse-image-1.0/text-to-image",
            prompt=job.prompt,
            size=job.size,
        )
        db.record_success(job.id, result)
    except TransientError as e:
        queue.requeue(job.id, backoff=e.retry_after)
    except ValidationError as e:
        db.record_failure(job.id, reason=str(e))

Храните столбец состояния для каждой задачи (pending, done, failed) и предусмотрите представление очереди недоставленных для сбоев. По завершении пакета сообщайте количество по типу съёмки и размеру, а не только общую сумму — именно там скрываются регрессии.

Чек-лист QA перед публикацией сгенерированных изображений

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

Автоматические проверки перед ревью:

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

Ручное ревью перед публикацией:

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

Записывайте рецензента и версию промпта для каждого одобренного материала. Когда поступит жалоба клиента или запрос на снятие с публикации, этот след позволит за один раз найти все затронутые изображения — и перегенерировать или снять всю группу.

Начните с одного типа съёмки, одного размера и небольшой выборки товаров, прогоните через интерфейс HiAPI и расширяйте шаблон только после того, как вывод пройдёт ревью.

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

Все статьи →

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

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

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