기능 · 마네킹 생성

AI 마네킹 생성 API 자체 모델용

한 줄 요약

Photta의 마네킹 생성 API는 선택한 속성을 기반으로 실사 수준의 AI 모델을 생성하고 재사용 가능한 마네킹 id를 반환하며 4 credits가 차감됩니다. 두 가지 빌더(의류용 빌더, 주얼리 클로즈업 특화 빌더)를 제공합니다.

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

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

POST/api/v1/mannequins/generate
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/mannequins/generate \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "Female",
  "ethnicity": "east_asian_korean",
  "age": "late_20s",
  "skin_tone": "light_medium",
  "expression": "neutral",
  "hair_style": "long_straight",
  "hair_color": "black",
  "body_type": "slim",
  "height": "average"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

한눈에 보기

한눈에 보기

엔드포인트
POST /api/v1/mannequins/generate
인증
Bearer API 키
처리 방식
비동기 — 상태 엔드포인트 폴링
일반적인 소요 시간
30-60s
크레딧
4 크레딧
입력 제한
이미지당 최대 10 MB; JPEG, PNG, WebP
멱등성
아니요

요청 및 응답

요청

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/mannequins/generate \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "Female",
  "ethnicity": "east_asian_korean",
  "age": "late_20s",
  "skin_tone": "light_medium",
  "expression": "neutral",
  "hair_style": "long_straight",
  "hair_color": "black",
  "body_type": "slim",
  "height": "average"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / 완료됨

{
  "data": {
    "id": "mmk_r4s5t6",
    "status": "processing",
    "category": "Female",
    "credits_used": 4,
    "created_at": "2026-04-10T14:00:00Z"
  },
  "request_id": "req_mnk002"
}

요청 파라미터

category

타입: string필수

Mannequin category.

값: FemaleMaleGirlChildBoyChild
ethnicity

타입: string

Ethnic appearance.

값: east_asian_koreaneast_asian_chinesesoutheast_asiansouth_asiannordicwestern_europeaneastern_europeanmediterraneanafricanafrican_americanmiddle_easternlatin_americanbrazilianmixed_asian_europeanpolynesian
age

타입: string

Age range.

값: early_20slate_20searly_30slate_30s40s50sbaby_1toddler_2_4young_5_7child_8_10preteen_11_13
skin_tone

타입: string

Skin tone.

값: lightlight_mediummediummedium_darkdark
face_shape

타입: string

Face shape.

값: ovalsquareroundheartoblongdiamond
eye_color

타입: string

Eye color.

값: browndark_brownblackbluegreenhazelgrayamber
eye_shape

타입: string

Eye shape.

값: almondroundmonolidhoodedupturneddownturned
expression

타입: string

Facial expression.

값: neutralsoft_smilewarm_smileseriousconfidentfriendly
facial_hair

타입: string

Facial hair style (Male only).

값: nonelight_stubblemedium_stubbleshort_beardfull_beardgoateemustache
makeup

타입: string

Makeup style (Female only).

값: naturalminimalsoft_glamprofessionaleditorial
hair_style

타입: string

Hair style. Available options depend on category — use /options endpoint.

hair_color

타입: string

Hair color.

값: blackdark_brownmedium_brownlight_brownauburnredblondeplatinum_blondegraywhite
hair_texture

타입: string

Hair texture.

값: straightwavycurlycoily
body_type

타입: string

Body type. Options depend on category — use /options endpoint.

height

타입: string

Height.

값: shortaveragetall
glasses

타입: string

Glasses.

값: noneeyeglassessunglasses
freckles

타입: string

Freckles.

값: nonelightprominent
piercings

타입: string

Piercings.

값: noneearnosemultiple

오류

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는 웹훅을 전송하지 않습니다.

속성을 입력하면 재사용 가능한 모델이 출력됩니다

옵션을 확인하고, 속성을 선택해 전송한 뒤, 폴링을 거쳐 id를 재사용하세요.

  1. 단계 1

    API 키 생성

    마네킹 생성은 다른 모든 Photta 기능과 동일한 인증 정보 및 credit 잔액을 사용합니다.

  2. 단계 2

    옵션 카탈로그 조회

    GET `/api/v1/mannequins/generate/options`는 카테고리별로 달라지는 `hair_style` 및 `body_type` 목록을 포함하여 허용되는 모든 값을 반환합니다. enum 값을 하드코딩하지 말고 이 데이터를 기반으로 폼을 구성하세요.

  3. 단계 3

    마네킹 생성 요청(POST)

    `category`(`Female`, `Male`, `GirlChild`, `BoyChild`)와 함께 17가지 선택 속성(인종, 나이, 피부 톤, 얼굴형 및 눈 모양, 표정, 수염, 메이크업, 헤어, 체형, 키, 안경, 주근깨, 피어싱)을 포함하여 POST `/api/v1/mannequins/generate`를 호출하세요.

  4. 단계 4

    작업이 완료될 때까지 폴링

    `data.status`가 `completed` 또는 `failed`가 될 때까지 3초마다 GET `/api/v1/mannequins/generate/:id`를 호출하세요. 일반적인 완료 시간은 30초에서 60초입니다.

  5. 단계 5

    마네킹 재사용

    완료된 응답 본문에는 고유 id를 가진 `mannequin` 객체가 포함됩니다. 이후 try-on 또는 아이웨어 작업 시 이 id를 `mannequin_id`로 전달하면 모든 컷에서 동일한 얼굴이 유지됩니다.

개발자가 모델 생성 전에 자주 묻는 질문

AI 마네킹이란 무엇인가요?

캐스팅 대신 외형 속성을 직접 지정하여 생성한 모델입니다. id 형태로 반환되므로 동일한 얼굴, 헤어, 체형으로 카탈로그 내 모든 의류를 착용할 수 있습니다.

마네킹 생성 비용은 얼마인가요?

의류 빌더와 주얼리 빌더 모두 4 credits입니다. 생성된 기존 마네킹을 이후 촬영에 재사용할 때는 추가 비용이 들지 않으며, 모델이 아닌 try-on 비용만 지불하면 됩니다.

어떤 속성을 설정할 수 있나요?

`category`는 필수 항목입니다. 그 외 속성(인종, 나이, 피부 톤, 얼굴형, 눈 색상 및 모양, 표정, 수염, 메이크업, 헤어스타일, 색상 및 질감, 체형, 키, 안경, 주근깨, 피어싱)은 모두 선택 사항입니다. 허용되는 값은 옵션 endpoint에 나열되어 있습니다.

주얼리 빌더는 어떤 용도인가요?

POST `/api/v1/mannequins/jewelry/generate`는 주얼리 클로즈업 작업에 특화된 모델을 생성합니다. 전신 속성 대신 `jewelry_type`, `shot_type`, `camera_angle`, `background`, `lighting`을 전달받아 목선, 귀, 손 등이 근접 촬영에서도 자연스럽게 표현됩니다.

여러 촬영에서 동일한 모델을 재사용할 수 있나요?

네 — 바로 그것이 이 endpoint의 핵심 목적입니다. 생성된 마네킹 id는 의류 try-on, 주얼리 try-on, 아이웨어 스튜디오에서 `mannequin_id`로 전달하여 사용할 수 있습니다.

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

`data.status`가 `completed` 또는 `failed`가 될 때까지 3초마다 GET `/api/v1/mannequins/generate/:id`를 호출하세요. 주얼리 빌더는 자체 상태 경로로 폴링합니다.

관련 기능

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

5분 만에 API 체험하기

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

  • 30-60s
  • 4 크레딧
  • 비동기, 폴링
  • 600 requests/min
  • Bearer 키