Możliwość · Eyewear studio

API wirtualnego try-on okularów dla okularów korekcyjnych i przeciwsłonecznych

W jednym zdaniu

API eyewear studio od Photta przekształca jedno zdjęcie okularów korekcyjnych lub przeciwsłonecznych w gotowe ujęcie. Wybierz opcję product-only lub on-model, wyślij POST, wykonuj polling co 3 sekundy i pobierz plik, gdy status zmieni się na completed. 5 credits w 2K.

  • Typowy czas: 20–60 sec
  • Credits: 5 credits w 2K · 6 credits w 4K
  • Przetwarzanie: asynchroniczne, polling
  • Limity: 600 requests/min
  • Uwierzytelnianie: Klucz Bearer

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono

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
Przykładowy wynik

W skrócie

W skrócie

Endpoint
POST /api/v1/eyewear-studio
Uwierzytelnianie
Klucz API Bearer
Przetwarzanie
Asynchroniczne — odpytuj endpoint statusu
Typowy czas
20–60 sec
Credits
5 credits w 2K · 6 credits w 4K
Proporcje obrazu
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limity wejściowe
Do 10 MB na obraz; JPEG, PNG, WebP
Idempotentne
Nie

Żądanie i odpowiedź

Żądanie

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 / Completed

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

Parametry żądania

eyewear_image

Typ: stringWymagane

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

mode

Typ: 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

Wartości: product-onlyon-model
sub_tool

Typ: 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

Wartości: studio-shotflat-laylifestylefloating
mannequin_id

Typ: 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

Typ: string

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

= front

Wartości: frontthree-quarterside-profile
expression

Typ: string

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

= neutral

Wartości: neutralsoft-smileseriousconfident
lighting_style

Typ: string

On-model only: how the portrait is lit.

= soft-diffused

Wartości: soft-diffusedstudionaturaldramatic
frame_fit_style

Typ: string

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

= casual

Wartości: casualprofessionalfashion-editorialsporty
backdrop

Typ: string

Studio-shot only: the backdrop behind the eyewear.

= white

Wartości: whitegrayblackgradient
lighting

Typ: string

Studio-shot only: the lighting setup.

= soft

Wartości: softharddramaticnatural
surface

Typ: string

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

= marble

Wartości: marblewoodfabricconcretemetal
arrangement_style

Typ: string

Flat-lay only: how the composition is arranged.

= minimal

Wartości: minimalsymmetricscatteredlayered
props

Typ: string

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

= none

Wartości: noneplantsaccessoriestech
scene

Typ: string

Lifestyle only: the real-world setting.

= coffee-shop

Wartości: coffee-shopbeachurban-streetofficepark
mood

Typ: string

Lifestyle only: the color mood of the scene.

= warm

Wartości: warmcoolvibrantmoody
angle

Typ: string

Floating only: the camera angle on the suspended frames.

= front

Wartości: frontthree-quartersidetop-down
shadow_style

Typ: string

Floating only: the shadow cast beneath the frames.

= soft-drop

Wartości: soft-dropnonehard-dropreflection
background_color

Typ: string

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

= white

Wartości: whitegrayblackbeige
background_prompt

Typ: string

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

aspect_ratio

Typ: string

Output aspect ratio.

= 3:4

Wartości: 3:41:14:39:1616:9
resolution

Typ: string

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

= 2K

Wartości: 2K4K

Błędy

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.

Limity

  • 600 żądań na minutę na klucz API (Stałe okno czasowe; limit jest taki sam w każdym planie)
  • Odpowiedź 429 zawiera nagłówek Retry-After: 30 s
  • Do 10 MB na obraz
  • Formaty: JPEG, PNG, WebP
  • Jednoczesne zadania wsadowe w zależności od planu: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Tylko polling — API nie wysyła webhooków.

Jedno zdjęcie oprawek na wejściu, jedno wystylizowane ujęcie okularów na wyjściu

Wybierz tryb, ustaw dostępne dla niego opcje stylizacji, wyślij żądanie, wykonaj polling i pobierz wynik.

  1. Krok 1

    Wygeneruj klucz API

    Eyewear studio korzysta z tych samych danych uwierzytelniających i tej samej puli credits, co każda inna funkcja Photta.

  2. Krok 2

    Wybierz tryb i jego stylizację

    `mode` przyjmuje wartość `product-only` lub `on-model`. Wariant product-only wymaga pola `sub_tool` — `studio-shot`, `flat-lay`, `lifestyle` lub `floating` — a każdy z nich udostępnia własne parametry sterujące. Wariant on-model wymaga `mannequin_id` oraz `face_angle`, `expression`, `lighting_style` i `frame_fit_style`.

  3. Krok 3

    Wyślij zadanie dla okularów metodą POST

    Wyślij żądanie POST pod `/api/v1/eyewear-studio` z polem `eyewear_image` oraz polami stylizacji. Pole `background_prompt` przyjmuje do 400 znaków i nadpisuje `background_color`. Polling jest jedynym sposobem sprawdzenia ukończenia zadania — API nie wysyła webhooków.

  4. Krok 4

    Wykonuj polling do momentu ukończenia zadania

    Wysyłaj GET pod `/api/v1/eyewear-studio/:id` co 3 sekundy, dopóki `data.status` nie przyjmie wartości `completed` lub `failed`; typowy czas realizacji wynosi od 20 do 60 sekund.

  5. Krok 5

    Pobierz i zapisz

    Odpowiedź po ukończeniu zadania zawiera `output_url` oraz miniaturę. Zapisz plik we własnym magazynie — traktuj ten URL jako jednorazowe dostarczenie wyniku zadania, a nie stały hosting.

Pytania, które programiści zadają przed wdrożeniem generowania zdjęć okularów

Do czego służy API eyewear studio?

Pobiera jedno zdjęcie produktowe okularów korekcyjnych lub przeciwsłonecznych i zwraca ich wystylizowaną fotografię — same oprawki w aranżacji studyjnej, flat-lay, lifestyle lub floating albo założone na twarz wybranego modela AI.

Ile kosztuje wygenerowanie zdjęcia okularów?

5 credits w 2K i 6 credits w 4K — dokładnie tyle samo, co try-on odzieży i biżuterii. Opłata za nieudane zadania jest zwracana automatycznie.

Jaka jest różnica między product-only a on-model?

`product-only` generuje zdjęcia samych oprawek i jest konfigurowany przez `sub_tool`. `on-model` umieszcza je na twarzy modela AI i jest sterowany parametrami `mannequin_id`, `face_angle`, `expression`, `lighting_style` oraz `frame_fit_style`. Pola należące do drugiego trybu są ignorowane.

Jakie opcje stylizacji udostępnia każdy sub-tool?

`studio-shot` przyjmuje `backdrop` i `lighting`. `flat-lay` przyjmuje `surface`, `arrangement_style` i `props`. `lifestyle` przyjmuje `scene` i `mood`. `floating` przyjmuje `angle` i `shadow_style`. Każde z tych pól jest enumem, więc nieobsługiwana wartość zostanie odrzucona zamiast dopasowywana na ślepo.

Czy mogę użyć własnego modelu AI?

Tak. `mannequin_id` akceptuje dowolny identyfikator manekina z GET `/api/v1/eyewear-studio/mannequins`, a manekiny wygenerowane za pomocą API generowania manekinów mogą być używane w ten sam sposób.

Jak odpytywać (poll) o wynik?

Wykonuj GET `/api/v1/eyewear-studio/:id` co 3 sekundy, aż `data.status` przyjmie wartość `completed` lub `failed`. Brak webhooków; polling jest udokumentowanym sygnałem ukończenia zadania.

Powiązane możliwości

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono

Wypróbuj API w 5 minut

Wygeneruj klucz Photta API, wklej powyższy snippet cURL, a otrzymasz swoje pierwsze zdjęcie na modelu, zanim zaparzy się kawa.

  • 20–60 sec
  • 5 credits w 2K · 6 credits w 4K
  • asynchroniczne, polling
  • 600 requests/min
  • Klucz Bearer