기능 · 상세 사진

상품 상세 사진 API 클로즈업용

한 줄 요약

Photta의 상세 사진 API는 상품의 지정된 한 영역에 대한 클로즈업을 렌더링합니다. 무료 analyze 호출을 통해 촬영할 가치가 있는 디테일을 제안받을 수 있으며, generate 호출 비용은 해상도 티어 구분 없이 고정 3 credits입니다.

  • 일반적인 소요 시간: 20–60 sec
  • 크레딧: 3 크레딧
  • 처리 방식: 비동기, 폴링
  • 제한 사항: 600 requests/min
  • 인증: Bearer 키

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

POST/api/v1/detail-photos
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')

한눈에 보기

한눈에 보기

엔드포인트
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')

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"
}

요청 파라미터

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-closeup
source_type

타입: string

Tunes what is preserved in the close-up.

= apparel

값: appareljewelry

오류

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 키 생성

    상세 사진은 다른 모든 Photta 기능과 동일한 자격 증명 및 동일한 크레딧 잔액을 사용합니다.

  2. 단계 2

    촬영할 디테일 확인

    `product_image`와 함께 POST `/api/v1/detail-photos/analyze`를 호출하세요. 해당 상품에 대해 제안된 `detail_label`, `detail_description`, `framing` 값을 동기식으로 반환하며, 요금은 부과되지 않습니다.

  3. 단계 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. 단계 4

    작업이 완료될 때까지 폴링

    `data.status`가 `completed` 또는 `failed`가 될 때까지 3초마다 GET `/api/v1/detail-photos/:id`를 호출하세요. 일반적으로 20~60초 내에 완료됩니다.

  5. 단계 5

    다운로드 및 영구 저장

    완료된 응답 본문에는 `output_url`이 포함됩니다. 상세 사진은 메인 사진 옆 PDP 갤러리에 바로 배치할 수 있습니다.

개발자가 상세 사진 배포 전에 자주 묻는 질문

상세 사진 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`를 호출하세요. 분석 호출은 동기식으로 처리되므로 폴링할 필요가 없습니다.

관련 기능

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

5분 만에 API 체험하기

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

  • 20–60 sec
  • 3 크레딧
  • 비동기, 폴링
  • 600 requests/min
  • Bearer 키