빠른 시작

5분 안에 첫 번째 Photta 이미지를 생성하세요.

한 줄 요약

ai.photta.app에서 가입하고, API 키 생성을 클릭한 뒤 이를 PHOTTA_API_KEY로 export하세요. /api/v1/tryon/apparel로 POST 요청을 보낸 후 반환된 생성 ID를 상태가 completed로 바뀔 때까지 3초마다 폴링합니다. 일반적으로 1.5~4분 내에 완료됩니다.

API 키 발급받기문서 보기
  • 인증: Bearer 키
  • 처리 방식: 비동기, 폴링
  • 제한 사항: 600 requests/min

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

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

동작 원리

시작부터 첫 번째 이미지까지 5개의 명령어

터미널에 순서대로 붙여넣으세요. 모든 코드 스니펫은 독립적으로 실행 가능하며 curl + jq만 사용합니다.

  1. 단계 1

    API 키 생성

    ai.photta.app에서 회원가입 후 개발자 대시보드를 엽니다. API 키 생성을 클릭하세요. 라이브 키는 photta_live_로 시작합니다. 나머지 가이드에서 셸을 통해 키를 읽을 수 있도록 export하세요.

    # https://ai.photta.app → Developers → Generate API key
export PHOTTA_API_KEY="photta_live_xxxxx"
export PHOTTA_BASE_URL="https://api.photta.app/api/v1"

  2. 단계 2

    첫 try-on POST 요청 보내기

    제품 이미지 URL과 마네킹 ID를 포함하여 /api/v1/tryon/apparel 엔드포인트를 호출합니다. API는 즉시 202 Accepted를 반환하며 data.id에 생성 ID를 함께 제공합니다.

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

  3. 단계 3

    완료될 때까지 폴링

    3초마다 GET /api/v1/tryon/apparel/:id를 호출합니다. 일반적인 완료 시간은 1.5–4분입니다. 작업이 멈춰 스크립트가 무한정 대기하지 않도록 시도 횟수에 상한을 두십시오.

    # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
  RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/apparel/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
  sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'

  4. 단계 4

    출력 결과 영구 저장

    status가 completed로 바뀌면 data.output_url에 렌더링된 이미지가 담깁니다. 프로덕션 환경이 이미지 렌더링을 Photta CDN에 의존하지 않도록 해당 바이트를 자체 스토리지에 다운로드하십시오.

    OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url')
curl -sO "$OUTPUT_URL"
echo "Saved $(basename "$OUTPUT_URL")"

  5. 단계 5

    실패 모드를 명확히 처리하기

    HTTP 상태 코드에 따라 분기합니다. 402는 credits 부족, 429는 rate limit(Retry-After 준수), 5xx는 일시적인 서버 오류입니다. 모든 오류 본문에는 조치 가능한 머신 판독용 error.code가 포함됩니다.

    case "$STATUS_CODE" in
  402) echo "insufficient_credits_error — top up before retrying" ;;
  429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
  4??) echo "$BODY" | jq '.error.type, .error.message' ;;
  5??) echo "api_error — retry with backoff" ;;
esac

개발자가 자주 묻는 질문

시작하기 관련 질문

빠른 시작 가이드를 완료하는 데 얼마나 걸리나요?

가입, 키 발급, 첫 cURL 실행까지 5분이면 충분합니다. 생성 작업 자체에 1.5~4분이 소요되므로, 첫 착용 모델 이미지를 확인하기까지 총 10분 정도를 예상하십시오.

사용해 보려면 신용카드가 필요한가요?

신규 계정에는 결제 전 사용할 수 있는 체험용 credits가 제공됩니다. 프로덕션으로 전환할 준비가 되면 플랜을 구독하여 더 높은 월간 credit 잔여량과 빠른 rate limit을 이용하십시오.

어떤 endpoint부터 시작해야 하나요?

의류 try-on(/api/v1/tryon/apparel)입니다. 가장 널리 사용되며 문서화가 가장 잘 되어 있고, 다른 모든 Photta endpoint에서 재사용되는 비동기 + polling 패턴을 그대로 다룹니다. 여기에 익숙해지면 주얼리와 고스트 마네킹도 동일한 방식으로 작동합니다.

브라우저에서 직접 실행할 수 있나요?

아니요. API 키는 서버 측에 보관해야 합니다. 브라우저로 전송하면 모든 방문자에게 유출됩니다. 자체 백엔드(Next.js route handler, Express, Flask, Lambda)의 씬 프록시를 통해 호출을 라우팅하고, 브라우저는 해당 프록시와 통신하도록 하십시오.

관련 페이지

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

첫 이미지 생성까지 단 5분 남았습니다

API 키 발급받기API 살펴보기
  • Bearer 키
  • 비동기, 폴링
  • 600 requests/min