Интеграция · Virtual Try-On

Внедрите виртуальную примерку (virtual try-on) в свое приложение

В двух словах

Примите фото товара на своем бэкенде, отправьте его через POST на /api/v1/tryon/apparel с mannequin ID, опрашивайте полученный ID генерации через фоновый воркер (ни в коем случае не в потоке HTTP-запроса), пока статус не изменится на completed, затем сохраните output_url в собственное объектное хранилище и отобразите его в интерфейсе.

Получить API-ключПосмотреть API виртуальной примерки
  • Кредиты: 5 credits при 2K · 6 credits при 4K
  • Типичное время: 1.5–4 min
  • Обработка: async, polling

Все показатели на этой странице взяты из документации API Photta · проверено

Реальный продакшен-сценарий: пользователь загружает фото товара, ваш бэкенд ставит задачу на try-on в очередь Photta, воркер выполняет polling до готовности, а фронтенд показывает результат на модели. Никаких блокирующих запросов, утечек API-ключей и самодельных SDK.

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

Как это работает

От загрузки до готового изображения на модели

Шесть конкретных шагов. Первая интеграция обычно занимает от десяти до пятнадцати минут.

  1. Шаг 1

    Спроектируйте поток данных

    Устройство клиента → ваш бэкенд (загрузка) → Photta API (отправка) → Photta API (polling) → ваша база данных (зеркалирование статуса) → устройство клиента (рендеринг). Набросайте эту схему на бумаге до написания первой строчки кода: граница между вашим бэкендом и Photta — это самое важное.

  2. Шаг 2

    Сгенерируйте и сохраните API-ключ

    Боевые ключи начинаются с photta_live_. Сохраните ключ в переменной окружения. Никогда не передавайте его в браузер. Один ключ открывает доступ ко всем возможностям Photta — отдельные ключи для try-on, украшений или ghost mannequin не требуются.

  3. Шаг 3

    Настройте endpoint для загрузки

    Сначала сохраняйте фото товара от клиента в свое объектное хранилище. Передавать в Photta публичный URL проще, чем base64, к тому же это дает журнал аудита по каждому запросу.

  4. Шаг 4

    Отправьте задачу с сервера

    Выполните POST-запрос на /api/v1/tryon/apparel, передав URL товара, mannequin_id, resolution и aspect_ratio. API вернет 202 Accepted и ID генерации. Сохраните этот ID в своей базе данных, чтобы клиент опрашивал ваш собственный endpoint, а не API Photta.

  5. Шаг 5

    Запустите polling из фонового воркера

    Не выполняйте polling внутри HTTP-запроса: генерация занимает от 1.5 до 4 минут, что превышает таймауты большинства serverless-платформ. Используйте Trigger.dev, Inngest, BullMQ, Vercel Cron или собственную очередь, чтобы повторять запрос каждые 3 секунды до завершения задачи.

  6. Шаг 6

    Отобразите результат

    Когда статус сменится на completed, сохраните data.output_url в свою базу данных и отправьте событие в реальном времени (через WebSocket, SSE или long polling) на устройство клиента. Интерфейс заменит скелетон загрузки на готовое изображение. Готово.

Три сквозных примера кода

Обработчик загрузки, диспетчер задач, воркер для polling — всё необходимое для запуска функции в продакшен.

// POST /app/try-on → your backend upload handler
import { put } from "@vercel/blob";

export async function uploadProduct(file: File) {
  const { url } = await put(`products/${crypto.randomUUID()}.jpg`, file, {
    access: "public",
  });
  return url;
}
const res = await fetch("https://api.photta.app/api/v1/tryon/apparel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_type": "top",
    "product_images": [
      "https://cdn.yourstore.com/products/shirt-front.jpg"
    ],
    "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
    "product_category": "t_shirt",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "body_size": "M",
    "expression": "neutral",
    "user_instruction": "Keep the collar pattern crisp and centered."
  }),
});
const { data } = await res.json(); // data.id, data.status
// Trigger.dev / Inngest / BullMQ task
const BASE = "https://api.photta.app/api/v1";

export const pollTryOnTask = task({
  id: "poll-try-on",
  run: async ({ generationId, attempt = 0 }) => {
    const res = await fetch(`${BASE}/tryon/apparel/${generationId}`, {
      headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` },
    });
    const { data } = await res.json();
    if (data.status === "completed") return data.output_url;
    if (data.status === "failed") throw new Error(data.error_message);
    if (attempt >= 120) throw new Error("try-on timed out");
    // Re-schedule this same task after 3 seconds.
    return ctx.retry.after(3000, { generationId, attempt: attempt + 1 });
  },
});

Частые вопросы разработчиков

Вопросы перед релизом

Можно ли реализовать это без бэкенда?

Нет. Ваш API-ключ Photta должен оставаться на стороне сервера. Для этой цели бэкендом считается даже простой обработчик маршрута Next.js или Cloudflare Worker — главное, чтобы ключ находился там, где пользовательский агент не сможет его прочитать.

Как избежать зависания HTTP-запросов?

Никогда не выполняйте polling внутри обработчика запросов. Отправьте задачу синхронно, верните клиенту ID генерации и запускайте polling из фонового воркера. Клиент опрашивает ВАШ эндпоинт статуса, а не эндпоинт Photta — так управление rate limit ложится на вас, а не на каждого отдельного пользователя.

Что произойдет, если выполнение задачи прервется ошибкой?

При сбое Photta автоматически возвращает credits, а ответ содержит data.error_code + data.error_message. Покажите пользователю понятное сообщение и добавьте кнопку повтора, запускающую новую задачу.

Можно ли отображать реальный прогресс?

Photta не передает промежуточный прогресс — статус может быть processing, completed или failed. Хорошо работает прогресс-бар по таймеру, откалиброванный на интервал в 1.5–4 минуты, или простой скелетон загрузки. Не придумывайте фиктивные проценты.

Является ли URL результата постоянным?

CDN URL стабилен, но ваш продукт не должен полагаться на него для долгосрочного отображения. Скачайте байты один раз и сохраните их в собственном бакете S3/GCS/R2 — тогда PDP продолжит работать, даже если CDN Photta изменится.

Связанные страницы

Справочник

Все показатели на этой странице взяты из документации API Photta · проверено

Запустите виртуальный try-on за один вечер

Каждый пример кода на этой странице соответствует официальной документации Photta. Получите API-ключ, и рабочий прототип будет готов быстрее, чем сварится кофе.

Получить API-ключОткрыть quickstart