Разработка · Shopify

Создание приложения виртуальной примерки для Shopify

В двух словах

Приложение примерки для Shopify считывает фото товара через Admin API, отправляет его POST-запросом в Photta, опрашивает статус задачи через фоновый воркер, а затем передает готовый URL в Shopify через productCreateMedia.

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

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

Получите фото товара через Admin API, сгенерируйте try-on с помощью Photta и загрузите результат обратно в медиафайлы товара. Четыре вызова, никакой собственной обработки изображений.

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')

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

От карточки товара до изображения примерки

Настройте скоупы приложения, получите фото, отправьте задачу, запустите polling вне основного потока запроса, прикрепите медиафайл.

  1. Шаг 1

    Настройте скоупы приложения

    Приложению примерки требуется чтение товаров и запись медиафайлов. Запрашивайте только те продуктовые скоупы, которые действительно используются, — мерчанты обращают внимание на экран подтверждения прав.

  2. Шаг 2

    Получите API-ключ Photta

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

  3. Шаг 3

    Получите изображение товара

    Запросите первое изображение товара. Этот URL публично доступен — именно то, что ожидает эндпоинт Photta: никакой повторной загрузки и подписанных URL.

  4. Шаг 4

    Отправьте задачу на try-on

    Отправьте POST-запрос с изображением, манекеном и позой. Ответ возвращается мгновенно и содержит ID генерации; сам рендеринг еще не завершен.

  5. Шаг 5

    Выполняйте polling в фоновой задаче

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

  6. Шаг 6

    Прикрепите медиафайл

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

Четыре вызова: от начала до конца

Запрос к Photta и polling взяты напрямую из документации API; вызовы Shopify — стандартные методы Admin API.

// Shopify Admin GraphQL — the product's first image is your source photo
const query = `query($id: ID!) {
  product(id: $id) { title images(first: 1) { nodes { url } } }
}`;

const res = await admin.graphql(query, { variables: { id: productGid } });
const { data } = await res.json();
const productImage = data.product.images.nodes[0].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
async function waitFor(id) {
  for (let attempt = 0; attempt < 120; attempt++) {
    const res = await fetch(`https://api.photta.app/api/v1/tryon/apparel/${id}`, { 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 ?? "generation failed");
    await new Promise((r) => setTimeout(r, 3000));
  }
  throw new Error("timed out after 6 minutes");
}
// Shopify downloads the URL itself, so hand it the Photta output_url
const mutation = `mutation($id: ID!, $media: [CreateMediaInput!]!) {
  productCreateMedia(productId: $id, media: $media) {
    mediaUserErrors { field message }
  }
}`;

await admin.graphql(mutation, {
  variables: {
    id: productGid,
    media: [{ originalSource: outputUrl, mediaContentType: "IMAGE", alt: "Virtual try-on" }],
  },
});

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

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

Где должен храниться ключ Photta в приложении Shopify?

В переменных окружения вашего сервера приложений, ни в коем случае не в теме оформления, блоке приложения или ответе app proxy. Все, что доступно витрине магазина, может прочитать и покупатель.

Какие скоупы Shopify требуются для работы?

Чтение изображений товаров и запись медиафайлов товаров. Сервису Photta доступ к Shopify не нужен вовсе — ваше приложение выступает единственным связующим звеном.

Как обеспечить быстрый ответ вебхука?

Мгновенно подтверждайте прием запроса, ставьте задачу в очередь и запускайте polling из воркера. Генерация длится дольше допустимого времени обработки вебхука, поэтому ожидание ответа недопустимо внутри хендлера.

Можно ли тарифицировать мерчантов за каждое изображение?

Это зависит от вашей бизнес-модели. Photta списывает credits с вашего аккаунта за каждый вызов, поэтому себестоимость генерации известна заранее; наценку вы определяете сами.

Что делать, если у товара нет фотографии?

Пропустите его, не отправляя плейсхолдер. Эндпоинту требуется реальная фотография одежды, а заглушка просто потратит credits на изображение, которое никто не опубликует.

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

Материалы по теме

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

Фокусируйтесь на продукте, а не на инфраструктуре

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

Получить API-ключОткрыть руководство по быстрому старту