기능 · 상세 사진
상품 상세 사진 API 클로즈업용
한 줄 요약
Photta의 상세 사진 API는 상품의 지정된 한 영역에 대한 클로즈업을 렌더링합니다. 무료 analyze 호출을 통해 촬영할 가치가 있는 디테일을 제안받을 수 있으며, generate 호출 비용은 해상도 티어 구분 없이 고정 3 credits입니다.
- 일반적인 소요 시간: 20–60 sec
- 크레딧: 3 크레딧
- 처리 방식: 비동기, 폴링
- 제한 사항: 600 requests/min
- 인증: Bearer 키
이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: Photta API 문서 · 확인 완료
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/detail-photos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/detail-photos",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
},
)
data = res.json()["data"] # data["id"], data["status"]한눈에 보기
한눈에 보기
- 엔드포인트
- POST /api/v1/detail-photos
- 인증
- Bearer API 키
- 처리 방식
- 비동기 — 상태 엔드포인트 폴링
- 일반적인 소요 시간
- 20–60 sec
- 크레딧
- 3 크레딧
- 입력 제한
- 이미지당 최대 10 MB; JPEG, PNG, WebP
- 멱등성
- 아니요
요청 및 응답
요청
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/detail-photos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/detail-photos",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
},
)
data = res.json()["data"] # data["id"], data["status"]202 Accepted / 완료됨
{
"data": {
"id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
"status": "processing",
"detail_label": "collar stitching",
"framing": "extreme-closeup",
"credits_used": 3,
"created_at": "2026-07-30T14:20:00Z"
},
"request_id": "req_dtl001"
}{
"data": {
"id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
"status": "completed",
"detail_label": "collar stitching",
"framing": "extreme-closeup",
"output_url": "https://cdn.photta.app/generated/dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10-thumb.jpg",
"credits_used": 3,
"created_at": "2026-07-30T14:20:00Z",
"completed_at": "2026-07-30T14:20:42Z",
"duration_ms": 42000
},
"request_id": "req_dtl003"
}요청 파라미터
product_image타입: string필수
The source image — a completed generation's output_url or any product photo. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.
detail_label타입: string필수
The area to zoom into, e.g. "collar stitching", "cuff detail", "fabric weave on the chest", "pendant clasp". Max 100 characters.
detail_description타입: string
Extra guidance for the close-up. Max 400 characters.
framing타입: string
How tight the crop is: "extreme-closeup" — the detail fills ~90% of the frame (near-macro); "closeup" — ~70% with some surrounding context; "medium-closeup" — ~50% with body/outfit visible.
= medium-closeup
값:extreme-closeupcloseupmedium-closeupsource_type타입: string
Tunes what is preserved in the close-up.
= apparel
값:appareljewelry
오류
- 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 키 생성
상세 사진은 다른 모든 Photta 기능과 동일한 자격 증명 및 동일한 크레딧 잔액을 사용합니다.
단계 2
촬영할 디테일 확인
`product_image`와 함께 POST `/api/v1/detail-photos/analyze`를 호출하세요. 해당 상품에 대해 제안된 `detail_label`, `detail_description`, `framing` 값을 동기식으로 반환하며, 요금은 부과되지 않습니다.
단계 3
클로즈업 POST 요청
`product_image` 및 `detail_label`과 함께 `/api/v1/detail-photos`로 POST 요청을 보내세요. `framing`을 `extreme-closeup`, `closeup` 또는 `medium-closeup`으로 설정하고, `source_type`을 `apparel` 또는 `jewelry`로 지정한 후 최대 400자의 `detail_description`을 추가하세요.
단계 4
작업이 완료될 때까지 폴링
`data.status`가 `completed` 또는 `failed`가 될 때까지 3초마다 GET `/api/v1/detail-photos/:id`를 호출하세요. 일반적으로 20~60초 내에 완료됩니다.
단계 5
다운로드 및 영구 저장
완료된 응답 본문에는 `output_url`이 포함됩니다. 상세 사진은 메인 사진 옆 PDP 갤러리에 바로 배치할 수 있습니다.
Node.js, Python, cURL에서의 동일한 엔드포인트
Node.js
Node.js 환경의 상품 상세 사진 API
네이티브 fetch를 사용하여 Node.js 백엔드에서 Photta의 상품 상세 사진 API 기능을 호출하세요. SDK는 필요 없습니다: 키를 저장하고 작업을 제출한 뒤 결과를 폴링하면 됩니다.
읽기Python
Python 환경의 상품 상세 사진 API
requests 라이브러리를 사용하여 Python에서 Photta의 상품 상세 사진 API를 호출하세요. 30줄짜리 래퍼이자 httpx를 통한 비동기 지원이 가능하며, Django, FastAPI, Celery에서 원활하게 동작합니다.
읽기cURL
cURL 기반 상품 상세 사진 API
cURL을 사용해 셸에서 Photta의 상품 상세 사진 API 기능을 직접 호출하세요. 제출, polling, 다운로드까지 — 모든 스니펫은 스크립트 파이프라인 구축을 위해 jq와 연동됩니다.
읽기
개발자가 상세 사진 배포 전에 자주 묻는 질문
상세 사진 API란 무엇인가요?
매크로 렌즈를 사용하는 2차 스튜디오 촬영 대신, 한 장의 넓은 사진에서 칼라 스티칭, 버클, 가슴 부위 직조 등 상품의 지정된 한 영역의 클로즈업을 렌더링하는 엔드포인트입니다.
상세 사진 비용은 얼마인가요?
고정 3 credits입니다. 이 엔드포인트에는 해상도 티어가 없으며, 디테일을 제안하는 analyze 호출은 무료입니다.
analyze 엔드포인트는 무엇을 반환하나요?
`detail_label`, 해당 영역을 보여줄 가치가 있는 이유를 설명하는 `detail_description`, 권장 `framing`이 포함된 제안 목록을 반환합니다. 제안된 값을 그대로 generate 호출에 전달할 수 있습니다.
각 framing 옵션의 화각은 어느 정도인가요?
`extreme-closeup`은 프레임의 거의 전체를 디테일로 채우고, `closeup`은 주변 컨텍스트를 약간 유지하며, `medium-closeup`은 주변 의류나 제품 내에서의 디테일을 보여줍니다. 상품 단위가 아닌 디테일 단위로 선택하세요.
소스가 생성된 이미지여도 되나요?
네. `product_image`는 직접 준비한 제품 사진뿐만 아니라 완료된 생성 작업의 `output_url`도 https URL 또는 base64 data URI 형태로 전달받을 수 있습니다.
결과는 어떻게 폴링하나요?
`data.status`가 `completed` 또는 `failed`가 될 때까지 3초마다 GET `/api/v1/detail-photos/:id`를 호출하세요. 분석 호출은 동기식으로 처리되므로 폴링할 필요가 없습니다.
관련 기능
기능
가상 착용(Virtual try-on) API 의류용
의류를 AI 마네킹에 착용시키는 REST API입니다. 비동기식 처리, 1.5~4분의 생성 시간, 2K 기준 5 credits, 4K 기준 6 credits 소요. cURL, Node.js, Python 예제가 제공됩니다.
엔드포인트 보기기능
주얼리 try-on API 목걸이, 반지, 팔찌 및 귀걸이 지원
REST 방식으로 AI 모델에 목걸이, 반지, 팔찌, 귀걸이를 착용해 보세요. 2K 기준 5 credits, 내장 클로즈업 마네킹 제공, 반사광을 정밀하게 반영하는 Photta 공식 렌더링 파이프라인을 활용하세요.
엔드포인트 보기빌드
AI 제품 사진 촬영 서비스 구축하기
Photta의 가상 try-on API를 화이트라벨 SaaS로 재판매하기 위한 창업자 플레이북: 테넌트 키, 배치 fanout, credit별 결제, 현실적인 SLA.
엔드포인트 보기비교
Photta vs FASHN — AI 패션 API 나란히 비교하기
Photta 및 FASHN 비교: 엔드포인트, 크레딧 가격, 요금제 티어, 동시 요청 한도. 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 스니펫을 붙여넣기만 하면, 커피가 다 내려지기도 전에 첫 번째 모델 착용 컷을 받아볼 수 있습니다.
- 20–60 sec
- 3 크레딧
- 비동기, 폴링
- 600 requests/min
- Bearer 키