FASHN Try-On v1.6 API: рабочие примеры запросов на curl и Python

FASHN Try-On v1.6 — это модель виртуальной примерки (image-to-image) на hiapi. Вы передаёте ей два изображения — фотографию человека и фотографию одежды — и она возвращает合成的 изображение с надетой на человека одеждой. Эта статья — практическое руководство для разработчиков по fashn try-on api: включает реальный запрос к /v1/tasks, который я полностью прогнал, полную входную схему, сверенную с онлайн-валидатором параметров, а также производственные детали, не описанные в таблице параметров.

Страница модели и онлайн-демо: FASHN Try-On v1.6.

1. Что вы построите + предварительные требования

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

Вам понадобится:

• API-ключ (sk-...), который можно получить в разделе быстрый старт hiapi.
• Два публично доступных URL изображений: фотография человека для model_image и фотография одежды для garment_image.

2. Минимальный рабочий пример

Создание задачи (curl)

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fashn-tryon-v1.6",
    "input": {
      "model_image": "https://cdn.example.com/person.jpg",
      "garment_image": "https://cdn.example.com/shirt.png"
    }
  }'

Ответ — это принятая задача, а не готовое изображение:

{"code":200,"data":{"taskId":"tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ"},"message":"success"}

model_image и garment_image — единственные обязательные поля; у остальных есть значения по умолчанию.

Опрос результата (curl)

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ \
  -H "Authorization: Bearer sk-YOUR_KEY"

После завершения задачи вы получите data.status: "success", а изображение будет находиться в data.output[0].url:

{
  "code": 200,
  "data": {
    "status": "success",
    "model": "fashn-tryon-v1.6",
    "storage": "temp",
    "output": [
      { "type": "image", "url": "https://temp.hiapi.ai/.../...-0.png", "expireAt": 1793119887 }
    ]
  },
  "message": "success"
}

Здесь важен expireAt: результаты хранятся во временном хранилище (TTL около 7 дней). Скачайте или скопируйте эти байты немедленно — не используйте горячие ссылки.

Запуск на Python от начала до конца

import time, requests

API = "https://api.hiapi.ai"
KEY = "sk-YOUR_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def try_on(model_image, garment_image, **opts):
    payload = {
        "model": "fashn-tryon-v1.6",
        "input": {"model_image": model_image, "garment_image": garment_image, **opts},
    }
    r = requests.post(f"{API}/v1/tasks", json=payload, headers=HEADERS, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:                     # poll until terminal
        time.sleep(3)
        d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d.get("status") == "success":
            return d["output"][0]["url"]
        if d.get("status") in ("fail", "error"):
            raise RuntimeError(f"task failed: {d}")

url = try_on(
    "https://cdn.example.com/person.jpg",
    "https://cdn.example.com/shirt.png",
    category="tops", mode="quality",
)
print(url)

3. Входная схема (проверена на онлайн-валидаторе)

fashn-tryon-v1.6 использует закрытую схему — любое поле, не перечисленное ниже, будет отклонено, поэтому вы не можете протащить дополнительные нативные параметры FASHN, которые hiapi не предоставляет.

Поле	Обязательно	Тип	Допустимые значения
model_image	Да	string (URL)	Фотография человека
garment_image	Да	string (URL)	Фотография одежды
category	Нет	enum	tops, bottoms, one-pieces, auto
mode	Нет	enum	performance, balanced, quality
garment_photo_type	Нет	enum	auto, model, flat-lay
output_format	Нет	enum	png, jpeg
seed	Нет	integer	Для воспроизводимости
segmentation_free	Нет	boolean	—

Как я это проверил: отправка {"model":"fashn-tryon-v1.6","input":{}} возвращает

invalid input: model_image: missing required field "model_image"; garment_image: missing required field "garment_image"

Каждое перечисленное выше значение enum подтверждено отправкой недопустимого значения, например mode: value must be one of 'performance', 'balanced', 'quality'. Передача num_samples, num_images или любого поля вне таблицы возвращает additional properties '...' not allowed — никаких опций с несколькими сэмплами. Один запрос возвращает одно изображение; для разных результатов меняйте seed между вызовами.

4. Практики для производственной среды

• Валидация происходит до оплаты. Неверный ввод возвращает HTTP 400 с телом ответа {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: ..."}, и задача не создаётся — некорректные запросы не влекут расходов. Допустимый запрос возвращает code:200 с taskId.
• Повторяйте опрос, а не отправку. Каждый POST /v1/tasks создаёт новую (платную) задачу. Если запрос опроса завершился по тайм-ауту, продолжайте опрашивать уже имеющийся taskId; потеря ответа не означает сбой задачи.
• Используйте callback вместо опроса. Для пакетных сценариев вы можете зарегистрировать callback, чтобы hiapi уведомлял вас о достижении задачей конечного состояния, вместо собственного опроса — конкретные поля см. в справочной документации по единому асинхронному API. Примеры выше используют опрос.

5. Как прошёл один реальный запуск

Я выполнил минимальный запрос выше — фотографию человека 768×1152 и изображение одежды 768×1152, опустив mode и category:

• Задержка: на объекте задачи от created до completed около 13 секунд.
• Выход: один PNG размером 768×1152, то есть вертикальное изображение. Страница модели указывает, что размер выхода следует за фотографией человека (в её проверенных запусках получены размеры 972×1296 и 768×1152), и этот запуск соответствует этому — полей width/height/aspect_ratio нет, поэтому размер выходного изображения определяется размером фотографии человека.
• Путь состояний: при опросе сначала отображается archiving, затем success; storage равно temp.
• Значения по умолчанию действительно работают. Пропуск mode и category всё равно успешен, поэтому эти два URL изображений действительно единственные обязательные входные данные — модель автоматически распознаёт тип одежды.

Оплата рассчитывается по количеству выходных изображений и не зависит от выбранного mode; актуальные тарифы смотрите на странице цен.

Связанные ссылки

• Страница модели FASHN Try-On v1.6 и онлайн-демо
• Справочная документация по единому асинхронному (задачному) API
• Быстрый старт — получение API-ключа
• Цены

Часто задаваемые вопросы

Какие поля обязательны? Только model_image и garment_image, и оба должны быть публично доступными URL.

Можно ли за один вызов получить несколько вариантов? Нет — num_samples и num_images отклоняются схемой. Один запрос возвращает одно изображение; меняйте seed между вызовами, чтобы получить разные результаты.

Как управлять размером выхода? Напрямую задать его нельзя. Результат следует за размером фотографии человека — мой вход 768×1152 дал выход 768×1152.

Сколько действует URL результата? Результаты хранятся во временном хранилище с expireAt (около 7 дней). Скачайте эти байты немедленно.

Влияет ли режим качества на цену? Нет — независимо от performance, balanced или quality, оплата рассчитывается по количеству выходных изображений.