Руководство
Как использовать Google виртуальную примерку через HiAPI API: руководство по curl и Python
На этой странице
Чего ожидает модель google-virtual-try-on
Прежде чем писать какой-либо код, полезно понять входной контракт. Модель google-virtual-try-on — это задача композиции двух изображений: она принимает изображение человека/модели и изображение одежды и генерирует изображение человека, одетого в эту одежду.
Это означает, что ваши подготовительные шаги всегда имеют одну и ту же форму:
- Изображение человека, на котором субъект хорошо виден и кадрирован разумно — лучше всего работают снимки в полный рост или по пояс, поскольку модели нужно понимать геометрию тела.
- Изображение одежды, желательно на чистом или однотонном фоне, показывающее предмет, который вы хотите перенести на человека.
Оба входа передаются в виде URL изображений, а не в виде необработанных двоичных данных в теле запроса. Это позволяет держать нагрузку на запрос небольшой и сохраняет ваш собственный слой хранения (S3, GCS, CDN) источником истины. Таким образом, ваша задача — обеспечить, чтобы каждый URL был публично доступен перед вызовом — или подписан и действителен достаточно долго.
Есть несколько практических ограничений, которые стоит учесть заранее:
- Разрешение и соотношение сторон влияют на качество результата. Крошечные миниатюры или чрезмерно обрезанные входные данные обычно дают плохие результаты.
- Каждый вызов обрабатывает один предмет одежды. Если у товара на странице несколько цветов, выполняйте несколько вызовов, а не пытайтесь упаковать несколько предметов в один запрос.
- Подбор пар — ваша ответственность. Модель не проверяет, «подходит» ли одежда этому человеку; она просто синтезирует то, что вы предоставили. Хороший подбор пар (снимок в полный рост с платьем, снимок по пояс с курткой) заметно улучшает результат.
Рассматривайте этот шаг как контракт по активам: если вы можете надёжно создать два качественных URL для каждой задачи, остальная работа по интеграции — это прямолинейное построение конвейера.
Настройка вашего запроса к HiAPI
Все вызовы моделей HiAPI следуют одной и той же форме, поэтому как только один из них заработает, остальные потребуют лишь замены параметров. Вот что требуется для google-virtual-try-on.
Конечная точка и метод
Запрос отправляется методом POST на конечную точку вызова модели HiAPI для google-virtual-try-on. Вы используете один и тот же базовый URL и одни и те же учётные данные для всех моделей, что является основной причиной выбора маршрутизации через HiAPI вместо индивидуального подключения каждого провайдера.
Аутентификация
Аутентифицируйтесь с помощью ключа API HiAPI в заголовке Authorization, используя стандартный формат bearer-токена:
Authorization: Bearer $HIAPI_API_KEY
Держите ключ на серверной стороне. Никогда не распространяйте его в браузерных сборках или мобильных приложениях — проксирование через ваш собственный бэкенд не только безопаснее, но и даёт вам место для добавления ограничения скорости и логирования.
Тип содержимого
Отправляйте тело запроса в формате JSON:
Content-Type: application/json
Тело запроса
Тело запроса содержит идентификатор вашей модели и два URL изображений из предыдущего раздела — изображение человека и изображение одежды — а также любые необязательные параметры, которые предоставляет модель. Точные имена параметров указаны в документации рядом с моделью; копируйте их дословно, а не угадывайте, поскольку опечатки в именах полей обычно проявляются как ошибки валидации, а не как полезные подсказки.
Сохраните вашу конфигурацию
Поместите базовый URL, идентификатор модели и ключ в переменные окружения, чтобы один и тот же скрипт можно было использовать в предпроизводственной и производственной средах без изменений:
export HIAPI_API_KEY="your-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"
Настройка на этом завершена. Никакого SDK, никакого индивидуального подключения провайдеров.
Рабочий запрос curl
Самый быстрый способ убедиться, что ключ и нагрузка корректны, — это один вызов curl. Вот анатомия запроса к google-virtual-try-on:
curl -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "google-virtual-try-on",
"input": {
"model_image": "https://your-cdn.example.com/person-001.jpg",
"garment_image": "https://your-cdn.example.com/jacket-front.jpg"
}
}'
На что стоит обратить внимание:
- Оба поля изображений находятся внутри объекта
input, что изолирует параметры, специфичные для модели, в пространстве имён и отделяет их от полей маршрутизации. - URL должны быть доступны с сервера, а не с вашего ноутбука. Адрес
localhostили адрес, доступный только через VPN, не сработает. - В этом вызове нет шага загрузки файла. Если ваши активы ещё не на CDN, сначала загрузите их и используйте сгенерированные URL.
Сначала выполните вызов один раз и проверьте возвращённый сырой JSON, прежде чем что-либо строить на его основе. Для удобства чтения передайте вывод через форматтер:
curl -s -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | python -m json.tool
Сохранение тела запроса в файле request.json также поможет избежать ошибок кавычек в shell, когда нагрузка вырастет.
Тот же запрос на Python
Для любого сценария, кроме разового теста, переходите на Python. В примере ниже используется только стандартная библиотека плюс requests, поэтому его можно сразу поместить в скрипт, Lambda или небольшой сервис без дополнительного фреймворка.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
def try_on(person_url: str, garment_url: str, timeout: int = 120) -> dict:
payload = {
"model": "google-virtual-try-on",
"input": {
"model_image": person_url,
"garment_image": garment_url,
},
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(
f"{BASE_URL}/v1/models/google-virtual-try-on",
json=payload,
headers=headers,
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = try_on(
"https://your-cdn.example.com/person-001.jpg",
"https://your-cdn.example.com/jacket-front.jpg",
)
print(result)
Замечания по адаптации:
- Задавайте явный таймаут. Генерация изображений не мгновенна; таймаут по умолчанию в
requestsдля таких вызовов слишком агрессивен. Выберите значение с комфортным запасом выше вашей p99-задержки. - Используйте
json=payload, а неdata=json.dumps(payload). Это установит тип содержимого за вас и позволит избежать ошибок двойного кодирования. - Возвращайте разобранный JSON, а не объект ответа, чтобы вызывающая сторона случайно не зависела от внутренних деталей HTTP. Если вам нужны коды статуса для метрик, зафиксируйте их перед возвратом.
- Отделяйте клиент от рабочего процесса. В реальном сервисе функция выше принадлежит лёгкому клиентскому модулю; очередь, хранилище и повторные попытки находятся на уровень выше.
Если вы уже используете httpx или асинхронный фреймворк, преобразование механическое — нагрузка и заголовки полностью совпадают.
Чтение ответа
Ответ — это JSON. Рассматривайте его как небольшой конверт, в котором важны две вещи: успешно ли выполнена задача и где находится результат.
В целом следует проверить:
- Статус транспорта. 2xx означает, что запрос принят и обработан. 4xx означает, что в вашем запросе ошибка; 5xx означает, что проблема на стороне сервиса. Логируйте код статуса при каждом вызове — это самый дешёвый инструмент наблюдаемости, который вы можете добавить.
- Поля тела ответа. Нагрузка содержит результат генерации. Результат изображения возвращается в виде URL, указывающего на сгенерированный актив. Точные имена полей определяются схемой ответа модели; разбирайте защитно, а не предполагайте одиночную строку.
- Метаданные. Любые поля использования или длительности в ответе стоит фиксировать. Биллинг учитывается платформой, поэтому сохранение метаданных на каждый запрос позволит вам позже сверять собственные логи с панелью управления.
Надёжный разбор выглядит так:
data = try_on(person_url, garment_url)
outputs = data.get("output") or {}
image_url = outputs.get("image")
if not image_url:
raise RuntimeError(f"No image in response: {data}")
Что делать с результатом
Возвращённый URL — это сгенерированный актив, а не постоянный. Не передавайте его напрямую во фронтенд и не оставляйте без внимания. Вместо этого:
- Скачайте и переразместите. Немедленно получите байты и запишите их в собственный бакет с ключом, адресуемым по содержимому. Это отделит ваш продукт от политики хранения генератора.
- Записывайте происхождение. Сохраняйте входные URL, идентификатор модели и временную метку вместе с выходными данными. Когда продавец спросит, почему примерка выглядит именно так, вам понадобится воспроизвести точную задачу.
- Нормализуйте формат. Измените размер и преобразуйте в стандартный формат витрины магазина один раз при приёме, а не при каждом просмотре страницы.
Рассматривайте ответ как кратковременную передачу — разобрать, скачать, сохранить, отбросить — это масштабируемый шаблон.
Режимы отказа и стратегия повторных попыток
Не все сбои заслуживают повторной попытки. Слепые повторы превратят небольшой сбой вышестоящего сервиса в полную очередь дублирующихся задач и неожиданный счёт.
Сначала классифицируйте
Не повторяйте — исправьте запрос:
- Ошибки валидации класса
400: некорректный JSON, отсутствующие или неверно названные поля, тело запроса не соответствует ожидаемой модели структуре. 401/403: неверный или отсутствующий ключ API, либо у ключа нет доступа к этой модели. Повтор никогда не поможет.404: неверный идентификатор модели или путь конечной точки.- Недоступные URL изображений. Если URL человека или одежды возвращает 404 или таймаут при получении, генерация не может продолжиться. Проверяйте URL перед отправкой.
Повторяйте с задержкой:
429: вы ограничены по скорости. Отступите и уважайте этот сигнал.5xx: временная ошибка сервиса или вышестоящего компонента.- Сбои на сетевом уровне: сброс соединения, таймаут чтения.
Ограниченные повторы с джиттером
Ограничьте число попыток — три обычно считается верхним пределом — и используйте экспоненциальную задержку со случайным джиттером, чтобы группа воркеров не повторяла синхронно:
import random, time
def with_retry(fn, attempts=3, base=1.0):
for i in range(attempts):
try:
return fn()
except requests.HTTPError as e:
status = e.response.status_code if e.response is not None else None
if status is not None and 400 <= status < 500 and status != 429:
raise # client error: do not retry
if i == attempts - 1:
raise
time.sleep(base * (2 ** i) + random.uniform(0, 0.5))
Производственные меры защиты
- Идемпотентность на уровне задачи. Хешируйте пару входных URL в ключ задачи. Если тот же ключ уже выполняется или завершён, верните сохранённый результат вместо повторной отправки.
- Очередь недоставленных сообщений. После исчерпания повторов поместите задачу и весь её контекст в хранилище, а не отбрасывайте молча.
- Размыкатель цепи. Если частота ошибок превышает порог, прекратите отправку на время периода восстановления, а не продолжайте нагружать борющийся сервис.
- Оповещайте по форме, а не только по количеству. Всплеск 4xx после развёртывания обычно означает, что кто-то переименовал поле.
Проверяйте входные данные как можно раньше
Большинство «сбоев модели» на самом деле являются плохими входными данными. Сделайте дешёвую предварительную проверку: отправьте HEAD-запрос к каждому URL, проверьте тип содержимого и примерные размеры и отклоните явно непригодные активы, прежде чем тратить платный вызов. Эта одна привычка устранит большую часть вашего трафика повторных попыток.
Встраивание в реальный конвейер
Успешный вызов curl — это лишь демонстрация. Надёжная продуктовая функция требует немного больше структуры вокруг него.
Структурируйте поток по этапам
Рабочая декомпозиция:
- Приём. Продавец или внутренний пользователь отправляет изображение человека и изображение одежды. Сохраните оба в вашем объектном хранилище и сгенерируйте стабильные подписанные URL.
- Валидация. Проверьте доступность, формат и размеры. Отклоняйте на раннем этапе с понятными подсказками.
- Отправка. Вызовите
google-virtual-try-onчерез клиентский модуль. Запишите ключ задачи, идентификатор модели и входные URL в базу данных. - Материализация. После успеха скачайте сгенерированное изображение, преобразуйте в ваш стандартный формат и запишите в ваш CDN с детерминированным ключом.
- Публикация. Обновите запись задачи, чтобы она указывала на размещённый вами актив, и позвольте витрине магазина читать только из вашего собственного хранилища.
Каждый этап можно повторять независимо, и именно поэтому вся система отлаживаема. Если шаг 4 завершился неудачей, вам не нужно перезапускать генерацию.
Держите клиент лёгким
Поместите HTTP-вызов в небольшой модуль, а политику (повторы, параллелизм, таймауты, логирование) разместите вокруг него. Когда HiAPI добавит параметр к модели или вы захотите A/B-тестировать разные маршруты генерации изображений, вам нужно будет изменить только один файл.
Операционные привычки, которые стоит перенять
- Асинхронность по умолчанию. Генерация занимает секунды, иногда больше. Отправляйте из воркера, а не из обработчика запроса, в котором ждёт пользователь.
- Активное кэширование. Одна и та же пара человек плюс одежда никогда не должна генерироваться дважды. Адресуйте результаты по содержимому и проверяйте перед отправкой.
- Бюджетируйте с видимостью. Поскольку использование учитывается платформой, логируйте метаданные на каждый запрос и периодически сверяйтесь с вашей панелью HiAPI. Обнаруживайте вышедшие из-под контроля циклы повторов за часы, а не в конце месяца.
- Версионируйте промпты и параметры. Сохраняйте объект параметров вместе с каждой задачей, чтобы воспроизводить результаты после изменений.
- Отказывайте видимо для пользователя. Вечная анимация загрузки хуже честного «Мы не смогли это сгенерировать, попробуйте другое фото».
Следующие шаги
Та же форма запроса применима к другим моделям изображений HiAPI, поэтому клиент, который вы здесь построите, станет шаблоном для остальной части вашего конвейера. Как только вызов с двумя изображениями станет стабильным, просмотрите каталог моделей, чтобы увидеть, что ещё подходит для вашего рабочего процесса — аутентификация, обработка ошибок и шаблоны хранения останутся теми же.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий