기능 · 배치 고스트 마네킹

배치 고스트 마네킹 API 전체 카탈로그 대상

한 줄 요약

Photta의 배치 고스트 마네킹 endpoint는 의류 사진 배열을 받아 배치 id와 이미지별 아이템 id를 반환합니다. 전체 배치에 대한 credits가 사전에 예약되며, 배치를 폴링하여 집계된 상태를 확인할 수 있습니다.

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

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

POST/api/v1/ghost-mannequin/batch
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin/batch \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_images": [
    {
      "image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/shirt-front.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/trousers-front.jpg",
      "image_side": "front"
    }
  ],
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, buttoned up",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
A garment shown without its mannequin by the ghost mannequin API
출력 예시

한눈에 보기

한눈에 보기

엔드포인트
POST /api/v1/ghost-mannequin/batch
인증
Bearer API 키
처리 방식
비동기 — 상태 엔드포인트 폴링
일반적인 소요 시간
1.5–4 min per image
크레딧
2K에서 4 크레딧 · 4K에서 5 크레딧
화면비
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/ghost-mannequin/batch \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_images": [
    {
      "image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/shirt-front.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/trousers-front.jpg",
      "image_side": "front"
    }
  ],
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, buttoned up",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / 완료됨

{
  "data": {
    "batch_id": "gmb_x7y8z9",
    "status": "processing",
    "total": 3,
    "completed": 0,
    "failed": 0,
    "items": [
      {
        "id": "gm_p1q2r3",
        "status": "processing"
      },
      {
        "id": "gm_s4t5u6",
        "status": "processing"
      },
      {
        "id": "gm_v7w8x9",
        "status": "processing"
      }
    ],
    "style": "3d",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_reserved": 12,
    "created_at": "2026-04-10T16:05:00Z"
  },
  "request_id": "req_gmb001"
}

요청 파라미터

product_images

타입: array[object]필수

Array of image objects. Each object contains "image" (URL or base64), optional "back_image", and optional "image_side". API batch caps (5× the dashboard limit): Free/Hobby/Hobby v2 5, Seller/Starter 10, Brand/Pro 25, Studio/Premium 50.

angle

타입: string

Applied to all images. "side" reconstructs the side view from each front photo (plus back_image when provided) — see the single-generate endpoint for details.

= straight

값: straightbackside
style

타입: string

Applied to all images.

= 3d

값: 3dflat_lay
background_color

타입: string

Applied to all images.

= white

값: whitegraybeigeblack
resolution

타입: string

Applied to all images. "2K" = 4 credits each. "4K" = 5 credits each. 4K is produced natively in a single generation per item — pick it upfront; the resolution cannot be changed after creation. Note: 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

값: 2K4K
aspect_ratio

타입: string

Applied to all images. Note: 1:1 is not available at 4K resolution — 1:1 combined with 4K returns 400.

= 3:4

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

타입: string

Batch-level: one note applied to every item. Optional free-form string, max 400 characters (anything longer is silently truncated). A guarded steer for ambiguous rendering choices — e.g. "closed front", "cream interior lining", "buttoned up" — it never overrides the source garment, brand label, or structural reconstruction, and it is explicitly NOT a determinism/seed control.

brand_label_id

타입: string

Applied to all images. Brand label UUID returned by the Brand Labels API. API v1 request fields use snake_case; use brand_label_id.

오류

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 기능과 동일한 자격 증명 및 동일한 credits 잔액을 사용합니다.

  2. 단계 2

    이미지 배열 구성

    `product_images`는 의류당 하나의 객체를 받습니다: `image`, 그리고 선택 사항인 `back_image` 및 `image_side`. API 배치 한도는 Free 및 Hobby 5장, Seller 10장, Brand 25장, Studio 50장입니다.

  3. 단계 3

    배치 POST 요청

    POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution`, `aspect_ratio`는 모든 항목에 적용되며, `user_instruction`은 최대 400자의 단일 메모를 모든 항목에 추가합니다. 첫 번째 항목이 렌더링되기 전에 전체 배치에 대한 credits가 예약됩니다.

  4. 단계 4

    배치 폴링

    3초마다 GET `/api/v1/ghost-mannequin/batch/:id`를 호출하세요. 본문에는 `total`, `completed`, `failed` 및 항목별 세부 정보가 포함되어 있어, 마지막 의류가 완료되기 전에 다운로드를 시작할 수 있습니다.

  5. 단계 5

    각 결과 다운로드

    완료된 모든 항목에는 자체 `output_url`, `credits_used`, 소요 시간이 포함됩니다. 실패한 항목은 예약된 credits가 환불되며 `credits_refunded`에 보고됩니다.

Node.js, Python, cURL에서 동일한 endpoint 사용

배치 실행 전 개발자들이 묻는 질문

배치 endpoint는 어떤 이점이 있나요?

단 한 번의 요청으로 의류 사진 배열을 받아 백그라운드에서 처리합니다. 수십 개의 개별 작업을 추적할 필요 없이, 전체 현황을 볼 수 있는 배치 id와 사진별 아이템 id를 받을 수 있습니다.

한 배치에 몇 장의 이미지가 들어가나요?

API 배치 한도는 대시보드 제한의 5배로, Free 및 Hobby 5장, Seller 10장, Brand 25장, Studio 50장입니다. 플랜에서 허용하는 크기를 초과한 배치는 400을 반환합니다.

배치에 대한 credits는 어떻게 청구되나요?

전체 배치는 사전에 예약됩니다: 이미지 수에 이미지당 가격을 곱한 수치로, 2K 기준 4 credits 또는 4K 기준 5 credits입니다. 잔액이 예약 금액을 충당할 수 없으면 요청은 402를 반환하며 아무것도 렌더링되지 않습니다.

한 항목이 실패하면 어떻게 되나요?

배치의 나머지 항목은 계속 진행됩니다. 배치 본문은 `completed`와 함께 `failed`를 보고하며, 실패한 항목에 대해 예약된 credits는 `credits_refunded`로 반환됩니다.

동시에 몇 개의 배치를 실행할 수 있나요?

동시 진행 중인 배치는 플랜별로 제한됩니다: Free 1개, Hobby 2개, Seller 3개, Brand 4개, Studio 6개. 한도를 초과하여 제출하면 409가 반환됩니다. 활성 배치가 완료될 때까지 폴링한 후 다시 제출하세요.

배치는 어떻게 폴링하나요?

전체 집계 상태를 확인하려면 3초마다 GET `/api/v1/ghost-mannequin/batch/:id`를 호출하고, 의류별 세부 정보가 필요한 경우 표준 고스트 마네킹 상태 경로에서 개별 항목을 폴링하세요.

관련 기능

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

5분 만에 API 체험하기

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

계정 생성 후 API 키 발급받기문서 보기
  • 1.5–4 min per image
  • 2K에서 4 크레딧 · 4K에서 5 크레딧
  • 비동기, 폴링
  • 600 requests/min
  • Bearer 키