빌드 · Shopify

Shopify try-on 앱 구축하기

한 줄 요약

Shopify try-on 앱은 Admin API에서 상품 이미지를 읽어와 Photta로 POST 요청을 보내고, 백그라운드 워커에서 작업을 폴링한 뒤, productCreateMedia를 통해 완성된 URL을 Shopify에 전달합니다.

API 키 발급받기try-on endpoint 살펴보기
  • 크레딧: 2K에서 5 크레딧 · 4K에서 6 크레딧
  • 일반적인 소요 시간: 1.5–4 min
  • 처리 방식: 비동기, 폴링

이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: Photta API 문서 · 확인 완료

Admin API에서 상품 사진을 읽어오고, Photta로 try-on을 렌더링한 다음, 결과물을 상품 미디어로 다시 등록하세요. 직접 이미지를 처리할 필요 없이 단 4번의 호출로 끝납니다.

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

동작 원리

상품 페이지에서 try-on 이미지 생성까지

앱 스코프를 설정하고, 사진을 읽어와 요청을 제출하고, 요청 경로 밖에서 폴링한 뒤 미디어를 첨부합니다.

  1. 단계 1

    앱 스코프 설정

    try-on 앱은 상품을 읽고 미디어를 등록할 수 있어야 합니다. 앱에서 실제로 사용하는 상품 관련 스코프만 요청하세요. 판매자는 동의 화면을 꼼꼼히 확인합니다.

  2. 단계 2

    Photta API 키 발급받기

    환경당 하나의 키를 발급받아 앱의 서버 측 설정에 보관하세요. 이 키는 스토어프론트나 판매자의 브라우저로 절대 노출되지 않아야 합니다.

  3. 단계 3

    상품 이미지 읽어오기

    상품을 조회하여 첫 번째 이미지를 가져옵니다. 해당 URL은 공개 상태이므로 Photta endpoint의 요구 사항과 정확히 일치합니다. 재업로드나 서명된 URL을 관리할 필요가 없습니다.

  4. 단계 4

    try-on 작업 제출

    마네킹 및 포즈 정보와 함께 이미지를 POST하세요. 응답은 즉시 반환되며 generation id가 포함됩니다. 이 시점에는 아직 렌더링되지 않습니다.

  5. 단계 5

    백그라운드 작업에서 폴링

    Shopify는 웹훅 핸들러가 수 초 내에 응답할 것을 요구하지만, 생성 작업은 그보다 더 오래 걸립니다. 즉시 승인 응답을 보낸 후 큐에 등록하고, 워커에서 3초마다 폴링하세요.

  6. 단계 6

    미디어 첨부

    완성된 URL을 Shopify에 전달하면 Shopify가 파일을 직접 다운로드합니다. 갤러리가 독립적으로 유지될 수 있도록 여러분의 서버에도 이미지를 영구 보관하세요.

엔드투엔드 4단계 호출

Photta 요청 및 폴링은 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 개발자가 자주 묻는 질문

Shopify 앱 내에서 Photta 키는 어디에 보관해야 하나요?

앱 서버의 환경 변수에 보관해야 하며, 테마, 앱 블록, 앱 프록시 응답에는 절대 포함되어서는 안 됩니다. 스토어프론트에서 읽을 수 있는 데이터는 구매자도 읽을 수 있습니다.

이 작업에는 어떤 Shopify 스코프가 필요한가요?

상품 이미지 읽기 및 상품 미디어 쓰기 스코프가 필요합니다. Photta는 Shopify 접근 권한이 전혀 필요하지 않으며, 양쪽 모두와 통신하는 것은 오직 여러분의 앱뿐입니다.

웹훅 응답 속도는 어떻게 빠르게 유지하나요?

즉시 승인 응답을 반환하고 작업을 큐에 등록한 뒤 워커에서 폴링하세요. 생성 작업은 웹훅 핸들러의 권장 응답 시간보다 오래 걸리므로, 대기 작업을 핸들러 내에 두어서는 안 됩니다.

판매자에게 이미지당 요금을 청구할 수 있나요?

그것은 여러분이 결정할 가격 책정 정책입니다. Photta는 호출당 credits 단위로 계정에 비용을 청구하므로, 렌더링 전에 이미지당 비용을 미리 파악할 수 있습니다. 여기에 추가 마진을 얼마나 붙일지는 자유입니다.

상품에 사진이 없으면 어떻게 되나요?

대체 이미지를 전송하지 말고 작업을 건너뛰세요. endpoint에는 실제 의류 사진이 필요하며, 대체 이미지에 credits를 소모해 봐야 아무도 게시하지 않을 이미지만 생성될 뿐입니다.

관련 페이지

관련 참고 자료

이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: Photta API 문서 · 확인 완료

부수적인 작업 대신 앱 자체를 빠르게 배포하세요

이 페이지의 Photta 호출 코드는 API 문서에서 바로 가져온 것입니다. 키를 발급받으면 몇 분 안에 첫 번째 렌더링을 완료할 수 있습니다.

API 키 발급받기빠른 시작 가이드 읽어보기