기능 · 주얼리

주얼리 try-on API 목걸이, 반지, 팔찌 및 귀걸이 지원

한 줄 요약

Photta의 주얼리 try-on API는 주얼리 사진, jewelry_type(목걸이, 반지, 팔찌, 귀걸이), 마네킹 ID를 전달받아 클로즈업 모델 착용 사진을 반환합니다. POST 요청 후 3초마다 폴링하여 status가 completed로 바뀌면 다운로드하세요.

  • 일반적인 소요 시간: 1.5–4 min
  • 크레딧: 2K에서 5 크레딧 · 4K에서 6 크레딧
  • 처리 방식: 비동기, 폴링
  • 제한 사항: 600 requests/min
  • 인증: Bearer 키

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

POST/api/v1/tryon/jewelry
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/jewelry \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
  "jewelry_type": "necklace",
  "mannequin_id": "mnk_j9k1l2",
  "background": "soft window light on dark velvet",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "Make the pendant 10% smaller."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
A necklace rendered on an AI model by the jewelry try-on API
출력 예시

한눈에 보기

한눈에 보기

엔드포인트
POST /api/v1/tryon/jewelry
인증
Bearer API 키
처리 방식
비동기 — 상태 엔드포인트 폴링
일반적인 소요 시간
1.5–4 min
크레딧
2K에서 5 크레딧 · 4K에서 6 크레딧
화면비
3:4 · 1:1 · 4:3 · 9:16 · 16:9
입력 제한
이미지당 최대 10 MB; JPEG, PNG, WebP
멱등성
아니요

요청 및 응답

요청

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/jewelry \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
  "jewelry_type": "necklace",
  "mannequin_id": "mnk_j9k1l2",
  "background": "soft window light on dark velvet",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "Make the pendant 10% smaller."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / 완료됨

{
  "data": {
    "id": "jwl_a1b2c3",
    "status": "processing",
    "jewelry_type": "necklace",
    "mannequin_id": "mnk_j9k1l2",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-04-10T14:00:00Z"
  },
  "request_id": "req_jwl001"
}

요청 파라미터

jewelry_image

타입: string필수

URL or base64 data URI of the jewelry product image.

jewelry_type

타입: string필수

Type of jewelry.

값: necklaceearringsbraceletring
mannequin_id

타입: string필수

ID of the mannequin. Must be jewelry-compatible and have a matching close-up view for the given jewelry_type. Use GET /api/v1/mannequins?jewelry_type=necklace to find compatible mannequins.

background

타입: string

Optional. Pass a URL or base64 data URI to use a reference photo as the scene; pass any other string to use it as a free-form text description (e.g. "soft window light on dark velvet"). When omitted, the original mannequin backdrop is preserved.

resolution

타입: string

Output resolution. "2K" costs 5 credits per image; "4K" costs 6 credits per image. 4K is produced natively in a single generation — pick it upfront; the resolution cannot be changed after creation. 4K cannot be combined with aspect_ratio 1:1 (returns 400).

= 2K

값: 2K4K
aspect_ratio

타입: string

Output aspect ratio. 1:1 is not available at 4K resolution — that combination returns 400.

= 3:4

값: 3:41:14:39:1616:9
user_instruction

타입: string

Free-form refinement, e.g. "make the pendant 10% smaller", "keep the clasp visible at the back of the neck". Capped at 400 characters server-side; longer strings are silently truncated. Requests to change the jewelry's size, scale, or proportions are honored and take priority; any other instruction applies only where it does not conflict with reproducing the jewelry exactly from the reference image. Not a determinism or seed control.

오류

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred. Retry later.

제한 사항

  • API 키당 분당 600회 요청 (고정 윈도우 방식이며, 제한은 모든 요금제에서 동일합니다)
  • 429 응답에는 Retry-After: 30초 헤더가 포함됩니다
  • 이미지당 최대 10 MB
  • 지원 형식: JPEG, PNG, WebP
  • 요금제별 동시 배치 수: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • 폴링 전용 — API는 웹훅을 전송하지 않습니다.

작고 반사율이 높은 품목에 맞춰 재조정된 의류 플로우

클로즈업 마네킹 선택, 제출, 폴링, 다운로드.

  1. 단계 1

    API 키 생성

    의류와 동일한 플로우 — ai.photta.app → Developers → Generate API key. 하나의 키가 모든 엔드포인트에 작동하며, 하나의 크레딧 잔액으로 모든 기능을 사용할 수 있습니다.

  2. 단계 2

    클로즈업 마네킹 선택

    주얼리 마네킹 목록을 조회하거나 `POST /api/v1/mannequins/jewelry`로 직접 업로드하세요 — Photta는 작은 금속과 보석에 맞게 피부 텍스처를 조정한 전용 클로즈업 마네킹 세트를 유지 관리합니다.

  3. 단계 3

    주얼리 작업 POST 요청

    `jewelry_image`, `jewelry_type`, `mannequin_id` 및 선택적 파라미터 `background`, `resolution`, `aspect_ratio`와 함께 `/api/v1/tryon/jewelry`로 POST 요청을 보냅니다. 서비스가 주얼리 카테고리에 맞춰 배치를 자동으로 리사이징합니다.

  4. 단계 4

    작업이 완료될 때까지 폴링

    3초마다 GET `/api/v1/tryon/jewelry/:id` 호출. 응답 형태는 의류와 동일합니다 — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. 단계 5

    다운로드 및 저장

    타이트한 1:1 크롭은 PDP 썸네일에 가장 적합하며, 더 넓은 화면비는 에디토리얼에 적합합니다. CDN을 핫링크하는 대신 바이트 데이터를 직접 저장하세요.

주얼리 try-on 배포 전 개발자들이 묻는 질문

어떤 주얼리 카테고리가 지원되나요?

목걸이, 반지, 팔찌, 귀걸이의 4가지 명시적 카테고리를 지원합니다. 각 카테고리에는 전용 클로즈업 마네킹 세트와 해당 폼팩터에 맞춘 배치 휴리스틱이 있습니다. 반지와 귀걸이는 1:1 화면비에서 가장 효과적이며, 목걸이는 3:4에서 잘 표현됩니다.

주얼리 try-on 비용은 얼마인가요?

의류와 동일합니다: 2K에서 5 credits, 4K에서 6 credits. 실패한 작업은 자동으로 환불됩니다. 클로즈업 마네킹 라이브러리에 대한 추가 요금은 없습니다.

주얼리 엔드포인트는 의류 엔드포인트와 어떻게 다른가요?

인증 방식, 폴링 패턴, 응답 형태는 동일하며 요청 본문만 다릅니다. `product_type` 및 `product_images` 대신 `jewelry_type` 및 `jewelry_image`를 전송하고, 주얼리 카테고리로 필터링된 마네킹을 선택합니다. 그 외의 모든 것(2K/4K, 화면비, credits)은 동일합니다.

자체 주얼리 모델을 업로드할 수 있나요?

네 — `POST /api/v1/mannequins/jewelry`는 커스텀 클로즈업 레퍼런스를 수락하며, `POST /api/v1/mannequins/jewelry/generate`는 옵션을 통해 새 모델을 생성합니다. 두 엔드포인트 모두 try-on 요청에 다시 전달할 수 있는 ID를 반환합니다.

반사율이 높은 금속과 원석은 어떻게 처리하나요?

클로즈업 파이프라인은 정반사 하이라이트 및 미세 지오메트리에 대한 메타데이터를 유지합니다. 일반적인 try-on 파이프라인에서 발생하는 고스팅이나 색 번짐 없이 금, 은, 경면 연마 플래티넘을 정확하게 렌더링합니다. 최상의 결과를 위해 초고화질 스튜디오 배경을 권장합니다.

결과는 어떻게 폴링하나요?

3~5초마다 GET `/api/v1/tryon/jewelry/:id`를 호출합니다. 의류와 동일한 상태 라이프사이클을 가집니다: `processing` → `completed` 또는 `failed`. 대다수의 작업은 1.5분에서 4분 내에 완료됩니다.

관련 기능

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

5분 만에 API 체험하기

Photta API 키를 발급받고 위 cURL 스니펫을 붙여넣기만 하면, 커피가 다 내려지기도 전에 첫 번째 모델 착용 컷을 받아볼 수 있습니다.

  • 1.5–4 min
  • 2K에서 5 크레딧 · 4K에서 6 크레딧
  • 비동기, 폴링
  • 600 requests/min
  • Bearer 키