HiAPI
Блог

Руководство

Как использовать Google виртуальную примерку через HiAPI API: руководство по curl и Python

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

Чего ожидает модель 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. Рассматривайте его как небольшой конверт, в котором важны две вещи: успешно ли выполнена задача и где находится результат.

В целом следует проверить:

  1. Статус транспорта. 2xx означает, что запрос принят и обработан. 4xx означает, что в вашем запросе ошибка; 5xx означает, что проблема на стороне сервиса. Логируйте код статуса при каждом вызове — это самый дешёвый инструмент наблюдаемости, который вы можете добавить.
  2. Поля тела ответа. Нагрузка содержит результат генерации. Результат изображения возвращается в виде URL, указывающего на сгенерированный актив. Точные имена полей определяются схемой ответа модели; разбирайте защитно, а не предполагайте одиночную строку.
  3. Метаданные. Любые поля использования или длительности в ответе стоит фиксировать. Биллинг учитывается платформой, поэтому сохранение метаданных на каждый запрос позволит вам позже сверять собственные логи с панелью управления.

Надёжный разбор выглядит так:

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 — это лишь демонстрация. Надёжная продуктовая функция требует немного больше структуры вокруг него.

Структурируйте поток по этапам

Рабочая декомпозиция:

  1. Приём. Продавец или внутренний пользователь отправляет изображение человека и изображение одежды. Сохраните оба в вашем объектном хранилище и сгенерируйте стабильные подписанные URL.
  2. Валидация. Проверьте доступность, формат и размеры. Отклоняйте на раннем этапе с понятными подсказками.
  3. Отправка. Вызовите google-virtual-try-on через клиентский модуль. Запишите ключ задачи, идентификатор модели и входные URL в базу данных.
  4. Материализация. После успеха скачайте сгенерированное изображение, преобразуйте в ваш стандартный формат и запишите в ваш CDN с детерминированным ключом.
  5. Публикация. Обновите запись задачи, чтобы она указывала на размещённый вами актив, и позвольте витрине магазина читать только из вашего собственного хранилища.

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

Держите клиент лёгким

Поместите HTTP-вызов в небольшой модуль, а политику (повторы, параллелизм, таймауты, логирование) разместите вокруг него. Когда HiAPI добавит параметр к модели или вы захотите A/B-тестировать разные маршруты генерации изображений, вам нужно будет изменить только один файл.

Операционные привычки, которые стоит перенять

  • Асинхронность по умолчанию. Генерация занимает секунды, иногда больше. Отправляйте из воркера, а не из обработчика запроса, в котором ждёт пользователь.
  • Активное кэширование. Одна и та же пара человек плюс одежда никогда не должна генерироваться дважды. Адресуйте результаты по содержимому и проверяйте перед отправкой.
  • Бюджетируйте с видимостью. Поскольку использование учитывается платформой, логируйте метаданные на каждый запрос и периодически сверяйтесь с вашей панелью HiAPI. Обнаруживайте вышедшие из-под контроля циклы повторов за часы, а не в конце месяца.
  • Версионируйте промпты и параметры. Сохраняйте объект параметров вместе с каждой задачей, чтобы воспроизводить результаты после изменений.
  • Отказывайте видимо для пользователя. Вечная анимация загрузки хуже честного «Мы не смогли это сгенерировать, попробуйте другое фото».

Следующие шаги

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

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

Все статьи →

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

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

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