Описание товаров по фото через API: как указать нейросети, на что обратить внимание

Мы развиваем Hayal — сервис работы с изображениями и видео. Для генерации в каталоге доступны GPT Image 2 (Low 1K, в том числе редактирование со своими фото), Z-Image Turbo (изображения по тексту до 2K), Anima (аниме и иллюстрации) и MiniMax H3 Turbo (короткие видео со звуком по тексту или фото). Есть и модели линейки Hayal. Актуальные варианты и стоимость собраны в каталоге https://hayal.tech/models. В этой статье речь об отдельной функции — описании изображения через API с указанием, на какие детали обратить внимание. Перечисленные модели генерации не являются выбором модели для метода /descriptions.

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

В Hayal для этого есть поле «На что обратить внимание». В API оно называется focus. Можно написать: «Опиши крой, рукава, застёжки и карманы. Не определяй состав ткани по фотографии». Эта инструкция помогает направить описание на вашу задачу и не увеличивает цену запроса.

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

Изображение и полные ответы: https://hayal.tech/image-description-api#example

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

Во втором запросе мы передали:

Опиши только видимые детали машины: цвет кузова, форму фар, решётку, колёса и зеркала. Фон не описывай. Не угадывай марку, материал, размеры или технические характеристики.

Получили такой ответ:

Цвет кузова машины красный. Фары имеют овальную форму. Решётка радиатора прямоугольная с горизонтальными элементами. Колёса чёрные с серебристыми дисками. Зеркала заднего вида чёрные, интегрированы в кузов.

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

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

Надписи и маркировка. Можно попросить обратить внимание на читаемые надписи и явно запретить додумывать неразборчивые символы. Это помощь при подготовке текста, а не гарантия точного OCR.

Alt-тексты. Можно выделить главный объект и его действие, исключить оценочные эпитеты. Полученный черновик нужно адаптировать к контексту страницы и нужной длине: параметр focus не гарантирует строго заданный формат ответа.

Осмотр видимых деталей. Можно направить внимание на царапины, сколы или состояние упаковки. Отсутствие замечания в ответе не доказывает отсутствие дефекта: для приёмки товара нужна отдельная проверка.

В профиле Hayal создаётся API-ключ. Запрос принимает ссылку на изображение либо файл через multipart/form-data. Для запроса по ссылке достаточно указать изображение, подробность и нужный акцент.

Пример тела JSON:

Отправлять его нужно методом POST на https://hayal.tech/api/v1/descriptions с заголовками Authorization: Bearer <API_KEY>, Content-Type: application/json и Idempotency-Key. Ключ API хранится на сервере приложения.

Успешный ответ содержит текст в data.description и использованное уточнение в data.focus. Само уточнение необязательно; максимальная длина — 1000 символов.

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

Полные примеры cURL, ответы и ошибки: https://hayal.tech/api-docs#description-focus

Краткое описание стоит 1 балл, подробное — 2 балла. Поле «На что обратить внимание» не добавляет плату. Баланс общий с сайтом; баллы списываются за успешный результат.

Рублёвая стоимость зависит от приобретённого пакета. Текущие цены и расчёт стоимости описания: https://hayal.tech/image-description-api#pricing опубликованы на странице API. Для оценки бюджета считайте отдельно число успешно обработанных изображений, выбранную подробность и дополнительные запросы при изменении задания.

Сейчас публичный API описания работает с изображениями JPG, PNG и WebP до 15 МБ и 40 мегапикселей. На аккаунт доступен один одновременно выполняемый запрос описания, поэтому обработку каталога нужно организовать через последовательную очередь.

Результат — обычный текст. Это не готовая структурированная карточка товара и не гарантированный JSON с характеристиками. Названия брендов, материалы, размеры, надписи и другие факты следует проверять перед публикацией. Описание видео есть в интерфейсе Hayal, но пока не доступно через публичный API.

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

Попробовать описание фото и подключить API Hayal: https://hayal.tech/image-description-api?utm_source=vc.ru&utm_medium=article&utm_campaign=description_api_focus