기능 · 주얼리
주얼리 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 문서 · 확인 완료
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')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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."
},
)
data = res.json()["data"] # data["id"], data["status"]
한눈에 보기
한눈에 보기
- 엔드포인트
- 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')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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."
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "jwl_a1b2c3",
"status": "completed",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"resolution": "2K",
"aspect_ratio": "3:4",
"output_url": "https://cdn.photta.app/generated/jwl_a1b2c3.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/jwl_a1b2c3-thumb.jpg",
"credits_used": 5,
"created_at": "2026-04-10T14:00:00Z",
"completed_at": "2026-04-10T14:01:10Z",
"duration_ms": 70000
},
"request_id": "req_jwl002"
}요청 파라미터
jewelry_image타입: string필수
URL or base64 data URI of the jewelry product image.
jewelry_type타입: string필수
Type of jewelry.
값:necklaceearringsbraceletringmannequin_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
값:2K4Kaspect_ratio타입: string
Output aspect ratio. 1:1 is not available at 4K resolution — that combination returns 400.
= 3:4
값:3:41:14:39:1616:9user_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.
오류
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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
API 키 생성
의류와 동일한 플로우 — ai.photta.app → Developers → Generate API key. 하나의 키가 모든 엔드포인트에 작동하며, 하나의 크레딧 잔액으로 모든 기능을 사용할 수 있습니다.
단계 2
클로즈업 마네킹 선택
주얼리 마네킹 목록을 조회하거나 `POST /api/v1/mannequins/jewelry`로 직접 업로드하세요 — Photta는 작은 금속과 보석에 맞게 피부 텍스처를 조정한 전용 클로즈업 마네킹 세트를 유지 관리합니다.
단계 3
주얼리 작업 POST 요청
`jewelry_image`, `jewelry_type`, `mannequin_id` 및 선택적 파라미터 `background`, `resolution`, `aspect_ratio`와 함께 `/api/v1/tryon/jewelry`로 POST 요청을 보냅니다. 서비스가 주얼리 카테고리에 맞춰 배치를 자동으로 리사이징합니다.
단계 4
작업이 완료될 때까지 폴링
3초마다 GET `/api/v1/tryon/jewelry/:id` 호출. 응답 형태는 의류와 동일합니다 — `data.status`, `data.output_url`, `data.thumbnail_url`.
단계 5
다운로드 및 저장
타이트한 1:1 크롭은 PDP 썸네일에 가장 적합하며, 더 넓은 화면비는 에디토리얼에 적합합니다. CDN을 핫링크하는 대신 바이트 데이터를 직접 저장하세요.
Node.js, Python, cURL에서 동일하게 사용하는 엔드포인트
Node.js
Node.js 환경의 주얼리 try-on API
네이티브 fetch를 사용하여 Node.js 백엔드에서 Photta의 주얼리 try-on API 기능을 호출하세요. SDK는 필요 없습니다: 키를 저장하고 작업을 제출한 뒤 결과를 폴링하면 됩니다.
읽기Python
Python 환경의 주얼리 try-on API
requests 라이브러리를 사용하여 Python에서 Photta의 주얼리 try-on API를 호출하세요. 30줄짜리 래퍼이자 httpx를 통한 비동기 지원이 가능하며, Django, FastAPI, Celery에서 원활하게 동작합니다.
읽기cURL
cURL 기반 주얼리 try-on API
cURL을 사용해 셸에서 Photta의 주얼리 try-on API 기능을 직접 호출하세요. 제출, polling, 다운로드까지 — 모든 스니펫은 스크립트 파이프라인 구축을 위해 jq와 연동됩니다.
읽기
주얼리 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분 내에 완료됩니다.
관련 기능
기능
가상 착용(Virtual try-on) API 의류용
의류를 AI 마네킹에 착용시키는 REST API입니다. 비동기식 처리, 1.5~4분의 생성 시간, 2K 기준 5 credits, 4K 기준 6 credits 소요. cURL, Node.js, Python 예제가 제공됩니다.
엔드포인트 보기기능
고스트 마네킹 API 투명 마네킹 제품 사진용
AI 고스트 마네킹 엔드포인트. 의류 사진에서 마네킹을 제거하고 내부 디테일을 보존합니다. 3D 또는 플랫레이, 배치 처리 지원, 2K 기준 4 credits.
엔드포인트 보기빌드
AI 제품 사진 촬영 서비스 구축하기
Photta의 가상 try-on API를 화이트라벨 SaaS로 재판매하기 위한 창업자 플레이북: 테넌트 키, 배치 fanout, credit별 결제, 현실적인 SLA.
엔드포인트 보기비교
Photta vs FASHN — AI 패션 API 나란히 비교하기
Photta 및 FASHN 비교: 엔드포인트, 크레딧 가격, 요금제 티어, 동시 요청 한도. 2026-04-19 기준 각 사의 공식 가격 정책 페이지에서 수집되었습니다. 가공된 수치는 일절 없습니다.
엔드포인트 보기비교
Photta vs Ayna — 개발자 API 또는 Shopify 우선 스튜디오
Photta vs Ayna 비교: 3개의 REST endpoint와 Shopify 중심 스튜디오 + API의 대결. 둘 다 장점이 있습니다. 2026-04-19에 각 사이트에서 수집한 데이터 기준입니다.
엔드포인트 보기빠른 시작
5분 안에 첫 번째 Photta 이미지를 생성하세요.
회원가입, API 키 생성, 첫 cURL 호출 실행, 완료될 때까지 폴링, 결과 저장까지. 엔드투엔드로 문서화된 5단계 가이드입니다.
엔드포인트 보기레퍼런스
Photta API 오류
Photta API의 전체 오류 유형 목록과 상태 코드, 오류 본문 포맷, 그리고 재시도할 가치가 있는 오류에 대한 안내입니다.
엔드포인트 보기레퍼런스
Photta API rate limits
Photta API rate limit, 윈도우, Retry-After 헤더, polling 주기, 플랜별 동시성 상한선 등 API 문서에 명시된 모든 내용입니다.
엔드포인트 보기
이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: Photta API 문서 · 확인 완료
5분 만에 API 체험하기
Photta API 키를 발급받고 위 cURL 스니펫을 붙여넣기만 하면, 커피가 다 내려지기도 전에 첫 번째 모델 착용 컷을 받아볼 수 있습니다.
- 1.5–4 min
- 2K에서 5 크레딧 · 4K에서 6 크레딧
- 비동기, 폴링
- 600 requests/min
- Bearer 키