빠른 시작

5분 안에 첫 번째 Photta 이미지 생성.

하나의 계정, 하나의 API 키, 다섯 개의 쉘 명령어. 아래 단계는 래퍼 코드, SDK, 프레임워크 제약 없이 Photta 공식 문서에서 권장하는 방식을 그대로 따릅니다.

요약

ai.photta.app에서 가입하고 API 키를 생성한 뒤 PHOTTA_API_KEY로 내보내세요. /api/v1/tryon/apparel로 POST하고 반환된 생성 ID를 완료될 때까지 3초마다 폴링하세요. 보통 1.5~4분 소요됩니다.

API 키 발급→문서 읽기

작동 원리

첫 이미지 생성을 위한 5가지 명령어

터미널에 순서대로 붙여넣으세요. 모든 스니펫은 독립적이며 curl과 jq만 사용합니다.

  1. 01

    단계 1

    API 키 생성

    ai.photta.app에 가입하고 개발자 대시보드를 엽니다. API 키를 생성하세요. 라이브 키는 photta_live_로 시작합니다. 쉘에서 읽을 수 있도록 키를 export 하세요.

    # Sign up at ai.photta.app, open the Developers dashboard,
# click "Generate API key" and copy it into your env.
export PHOTTA_API_KEY="photta_live_xxxxx"
export PHOTTA_BASE_URL="https://ai.photta.app/api/v1"
  2. 02

    단계 2

    첫 번째 가상 피팅 POST

    제품 이미지 URL, mannequin_id, pose_id와 함께 /api/v1/tryon/apparel을 호출하세요. API는 즉시 202 Accepted 응답을 주며 data.id에 생성 ID를 반환합니다.

    curl -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_type": "dress",
    "product_images": ["https://example.com/dress.jpg"],
    "mannequin_id": "mnq_athena_ts",
    "pose_id": "pose_standing_front",
    "resolution": "2K",
    "aspect_ratio": "3:4"
  }'
# Response: 202 Accepted + data.id (generation ID)
  3. 03

    단계 3

    완료까지 폴링

    3초마다 /api/v1/tryon/apparel/:id를 호출하세요. 보통 1.5–4분이 걸립니다. 작업이 무한정 대기하지 않도록 최대 시도 횟수를 설정하세요.

    # Loop every 3 seconds until status flips to "completed".
# Typical completion: 1.5–4 minutes. Max 120 attempts = 6 min.
for i in $(seq 1 120); do
  RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" \
    -H "Authorization: Bearer $PHOTTA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "Job failed" && exit 1
  sleep 3
done
  4. 04

    단계 4

    출력물 저장

    상태가 completed로 바뀌면 data.output_url에 렌더링된 이미지가 담깁니다. 렌더링 성능을 위해 Photta CDN에 의존하지 말고 자체 스토리지에 다운로드하세요.

    # Pull the final URL out of the response and save the bytes.
OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url')
curl -sO "$OUTPUT_URL"
echo "Saved $(basename "$OUTPUT_URL")"
  5. 05

    단계 5

    에러 상황 처리

    HTTP 상태 코드로 분기하세요: 크레딧 부족 시 402, rate limits 시 429(Retry-After 준수), 일시적 서버 에러 시 5xx. 모든 에러 본문에는 프로그램에서 처리 가능한 기계 판독용 error.code가 포함됩니다.

    # Surface the common failure modes honestly.
case "$STATUS_CODE" in
  402) echo "Out of credits — top up at ai.photta.app" ;;
  429) echo "Rate limited — honour Retry-After header" ;;
  4??) echo "Client error: $(echo "$BODY" | jq '.error.message')" ;;
  5??) echo "Server error — retry with backoff" ;;
esac

개발자 자주 묻는 질문

시작 전 궁금한 점

이 빠른 시작 가이드는 얼마나 걸리나요?+

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

테스트를 위해 신용카드가 필요한가요?+

아니요. 새 계정에는 유료 결제 전에 사용할 수 있는 체험용 크레딧이 제공됩니다. 프로덕션 배포 준비가 되면 더 많은 월간 크레딧과 빠른 rate limits를 제공하는 요금제를 구독하세요.

어떤 엔드포인트를 먼저 써봐야 할까요?+

의류 가상 피팅(/api/v1/tryon/apparel)을 추천합니다. 가장 많이 사용되는 기능이며 문서가 매우 상세하고, 다른 모든 Photta 엔드포인트가 재사용하는 비동기+폴링 패턴을 익힐 수 있기 때문입니다. 익숙해지면 주얼리와 고스트 마네킹도 동일한 방식으로 사용할 수 있습니다.

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

아니요. API 키는 반드시 서버 측에 보관해야 합니다. 브라우저에 키를 포함하면 모든 방문자에게 노출됩니다. 자체 백엔드(Next.js 라우트 핸들러, Express, Flask, Lambda 등)에 얇은 프록시를 두고 브라우저가 해당 프록시와 통신하도록 구현하세요.

빠른 시작

첫 이미지 확인까지 5분 남았습니다

API 키 발급 →API 탐색하기
Photta API 빠른 시작 — 5분 만에 첫 이미지 얻기 | Photta