기능 · 아이웨어 스튜디오

아이웨어 가상 try-on API 안경 및 선글라스용

한 줄 요약

Photta의 아이웨어 스튜디오 API는 안경 또는 선글라스 사진 한 장을 완성도 높은 연출 컷으로 변환합니다. 제품 단독 또는 모델 착용 모드를 선택해 POST 요청을 보내고, 3초마다 폴링하여 상태가 completed가 되면 다운로드하세요. 2K 기준 5 credits.

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

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

POST/api/v1/eyewear-studio
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/eyewear-studio \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
  "mode": "product-only",
  "sub_tool": "studio-shot",
  "backdrop": "gradient",
  "lighting": "soft",
  "aspect_ratio": "3:4",
  "resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
Sunglasses photographed by the eyewear studio API
출력 예시

한눈에 보기

한눈에 보기

엔드포인트
POST /api/v1/eyewear-studio
인증
Bearer API 키
처리 방식
비동기 — 상태 엔드포인트 폴링
일반적인 소요 시간
20–60 sec
크레딧
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/eyewear-studio \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
  "mode": "product-only",
  "sub_tool": "studio-shot",
  "backdrop": "gradient",
  "lighting": "soft",
  "aspect_ratio": "3:4",
  "resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / 완료됨

{
  "data": {
    "id": "eyw_7a1c9e42f05b3d688c2e4f01a9d6b357",
    "status": "processing",
    "mode": "product-only",
    "sub_tool": "studio-shot",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-08-01T09:15:00Z"
  },
  "request_id": "req_eyw001"
}

요청 파라미터

eyewear_image

타입: string필수

The eyewear product image — glasses or sunglasses. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

mode

타입: string

Generation mode: "product-only" — the eyewear alone, styled by sub_tool; "on-model" — the eyewear worn on an AI model's face (requires mannequin_id).

= product-only

값: product-onlyon-model
sub_tool

타입: string

Product-only styling: "studio-shot" — clean studio product shot; "flat-lay" — top-down arrangement on a surface; "lifestyle" — the eyewear placed in a real-world scene; "floating" — the frames suspended mid-air. Sending sub_tool with mode "on-model" returns 400.

= studio-shot

값: studio-shotflat-laylifestylefloating
mannequin_id

타입: string

Required when mode is "on-model": the AI model whose face wears the eyewear — an id ("mnk_...") from GET /api/v1/eyewear-studio/mannequins. Sending it in product-only mode returns 400.

face_angle

타입: string

On-model only: the angle of the model's face.

= front

값: frontthree-quarterside-profile
expression

타입: string

On-model only: the model's facial expression.

= neutral

값: neutralsoft-smileseriousconfident
lighting_style

타입: string

On-model only: how the portrait is lit.

= soft-diffused

값: soft-diffusedstudionaturaldramatic
frame_fit_style

타입: string

On-model only: the overall styling of how the frames are worn.

= casual

값: casualprofessionalfashion-editorialsporty
backdrop

타입: string

Studio-shot only: the backdrop behind the eyewear.

= white

값: whitegrayblackgradient
lighting

타입: string

Studio-shot only: the lighting setup.

= soft

값: softharddramaticnatural
surface

타입: string

Flat-lay only: the surface the eyewear lies on.

= marble

값: marblewoodfabricconcretemetal
arrangement_style

타입: string

Flat-lay only: how the composition is arranged.

= minimal

값: minimalsymmetricscatteredlayered
props

타입: string

Flat-lay only: complementary props placed around the eyewear.

= none

값: noneplantsaccessoriestech
scene

타입: string

Lifestyle only: the real-world setting.

= coffee-shop

값: coffee-shopbeachurban-streetofficepark
mood

타입: string

Lifestyle only: the color mood of the scene.

= warm

값: warmcoolvibrantmoody
angle

타입: string

Floating only: the camera angle on the suspended frames.

= front

값: frontthree-quartersidetop-down
shadow_style

타입: string

Floating only: the shadow cast beneath the frames.

= soft-drop

값: soft-dropnonehard-dropreflection
background_color

타입: string

Solid background color. Applies in both modes. Overridden by background_prompt when both are sent.

= white

값: whitegrayblackbeige
background_prompt

타입: string

Free-text background description. Max 400 characters — excess is silently truncated. Overrides background_color.

aspect_ratio

타입: string

Output aspect ratio.

= 3:4

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

타입: string

Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.

= 2K

값: 2K4K

오류

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

    모드 및 스타일링 선택

    `mode`는 `product-only` 또는 `on-model`입니다. product-only는 `sub_tool`(`studio-shot`, `flat-lay`, `lifestyle`, `floating`)을 사용하며 각 도구마다 고유한 제어 옵션을 제공합니다. on-model은 `mannequin_id`와 함께 `face_angle`, `expression`, `lighting_style`, `frame_fit_style`을 사용합니다.

  3. 단계 3

    아이웨어 작업 POST 요청

    `eyewear_image` 및 스타일링 필드와 함께 `/api/v1/eyewear-studio`로 POST 요청을 보냅니다. `background_prompt`는 최대 400자까지 지원하며 `background_color`보다 우선 적용됩니다. 완료 여부는 폴링으로만 확인할 수 있으며, API는 웹훅을 전송하지 않습니다.

  4. 단계 4

    작업 완료까지 폴링

    `data.status`가 `completed` 또는 `failed`가 될 때까지 3초마다 `/api/v1/eyewear-studio/:id`로 GET 요청을 보냅니다. 일반적으로 20~60초 내에 완료됩니다.

  5. 단계 5

    다운로드 및 저장

    완료된 응답 본문에는 `output_url`과 썸네일이 포함됩니다. URL은 일회성 작업 결과 전달용이며 영구 호스팅이 아니므로 파일을 직접 저장해야 합니다.

아이웨어 연출 컷 프로덕션 배포 전 자주 묻는 질문

아이웨어 스튜디오 API는 어떤 기능을 제공하나요?

안경 또는 선글라스 제품 사진 한 장을 입력받아 스타일링된 사진으로 반환합니다. 스튜디오, 플랫레이, 라이프스타일, 플로팅 기법을 적용한 제품 단독 컷이나 선택한 AI 모델 착용 컷으로 생성할 수 있습니다.

아이웨어 컷 생성 비용은 얼마인가요?

어패럴 및 주얼리 try-on과 동일하게 2K 해상도는 5 credits, 4K 해상도는 6 credits입니다. 실패한 작업은 자동으로 환불됩니다.

product-only와 on-model의 차이점은 무엇인가요?

`product-only`는 안경테 자체만 촬영하며 `sub_tool`로 제어합니다. `on-model`은 AI 모델의 얼굴에 안경을 착용시키며 `mannequin_id`, `face_angle`, `expression`, `lighting_style`, `frame_fit_style`로 제어합니다. 선택하지 않은 모드의 필드는 무시됩니다.

각 하위 도구는 어떤 스타일링 옵션을 제공하나요?

`studio-shot`은 `backdrop`과 `lighting`을 지원합니다. `flat-lay`는 `surface`, `arrangement_style`, `props`를 지원합니다. `lifestyle`은 `scene`과 `mood`를 지원합니다. `floating`은 `angle`과 `shadow_style`을 지원합니다. 모든 필드는 enum 형식이므로 정의되지 않은 값은 유추 처리되지 않고 거부됩니다.

자체 AI 모델을 사용할 수 있나요?

네. `mannequin_id`는 GET `/api/v1/eyewear-studio/mannequins`의 모든 마네킹 id를 허용하며, 마네킹 생성 API로 만든 마네킹도 동일한 방식으로 사용할 수 있습니다.

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

`data.status`가 `completed` 또는 `failed`가 될 때까지 3초마다 GET `/api/v1/eyewear-studio/:id`를 호출하세요. 웹훅은 제공되지 않으며, 폴링이 문서화된 완료 신호입니다.

관련 기능

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

5분 만에 API 체험하기

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

  • 20–60 sec
  • 2K에서 5 크레딧 · 4K에서 6 크레딧
  • 비동기, 폴링
  • 600 requests/min
  • Bearer 키