Funzionalità · Eyewear studio

API di try-on virtuale per occhiali per occhiali da vista e da sole

In sintesi

L'API eyewear studio di Photta trasforma una singola foto di occhiali da vista o da sole in uno scatto finito. Scegli solo prodotto o su modello, invia la POST, esegui il polling ogni 3 secondi, scarica quando lo stato è completed. 5 credits a 2K.

  • Tempo tipico: 20–60 sec
  • Credits: 5 credits a 2K · 6 credits a 4K
  • Elaborazione: asincrono, polling
  • Limiti: 600 richieste/min
  • Autenticazione: Chiave Bearer

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato

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
Esempio di output

Panoramica

Panoramica

Endpoint
POST /api/v1/eyewear-studio
Autenticazione
API key Bearer
Elaborazione
Asincrona — effettua il polling dell'endpoint di stato
Tempo tipico
20–60 sec
Credits
5 credits a 2K · 6 credits a 4K
Rapporti d'aspetto
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limiti di input
Fino a 10 MB per immagine; JPEG, PNG, WebP
Idempotente
No

Richiesta e risposta

Richiesta

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

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

Parametri della richiesta

eyewear_image

Tipo: stringObbligatorio

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

mode

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

Valori: product-onlyon-model
sub_tool

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

Valori: studio-shotflat-laylifestylefloating
mannequin_id

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

Tipo: string

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

= front

Valori: frontthree-quarterside-profile
expression

Tipo: string

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

= neutral

Valori: neutralsoft-smileseriousconfident
lighting_style

Tipo: string

On-model only: how the portrait is lit.

= soft-diffused

Valori: soft-diffusedstudionaturaldramatic
frame_fit_style

Tipo: string

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

= casual

Valori: casualprofessionalfashion-editorialsporty
backdrop

Tipo: string

Studio-shot only: the backdrop behind the eyewear.

= white

Valori: whitegrayblackgradient
lighting

Tipo: string

Studio-shot only: the lighting setup.

= soft

Valori: softharddramaticnatural
surface

Tipo: string

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

= marble

Valori: marblewoodfabricconcretemetal
arrangement_style

Tipo: string

Flat-lay only: how the composition is arranged.

= minimal

Valori: minimalsymmetricscatteredlayered
props

Tipo: string

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

= none

Valori: noneplantsaccessoriestech
scene

Tipo: string

Lifestyle only: the real-world setting.

= coffee-shop

Valori: coffee-shopbeachurban-streetofficepark
mood

Tipo: string

Lifestyle only: the color mood of the scene.

= warm

Valori: warmcoolvibrantmoody
angle

Tipo: string

Floating only: the camera angle on the suspended frames.

= front

Valori: frontthree-quartersidetop-down
shadow_style

Tipo: string

Floating only: the shadow cast beneath the frames.

= soft-drop

Valori: soft-dropnonehard-dropreflection
background_color

Tipo: string

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

= white

Valori: whitegrayblackbeige
background_prompt

Tipo: string

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

aspect_ratio

Tipo: string

Output aspect ratio.

= 3:4

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

Tipo: string

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

= 2K

Valori: 2K4K

Errori

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.

Limiti

  • 600 richieste al minuto per API key (Finestra fissa; il limite è lo stesso per ogni piano)
  • Un 429 restituisce Retry-After: 30 secondi
  • Fino a 10 MB per immagine
  • Formati: JPEG, PNG, WebP
  • Batch simultanei per piano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Solo polling — l'API non invia webhook.

Una foto della montatura in input, uno scatto rifinito degli occhiali in output

Scegli una modalità, seleziona lo styling esposto da tale modalità, invia, esegui il polling, scarica.

  1. Passaggio 1

    Genera una chiave API

    L'eyewear studio utilizza le stesse credenziali e lo stesso saldo di credits di ogni altra funzionalità Photta.

  2. Passaggio 2

    Scegli una modalità e il relativo styling

    `mode` è `product-only` o `on-model`. Product-only accetta un `sub_tool` — `studio-shot`, `flat-lay`, `lifestyle` o `floating` — e ciascuno abilita i propri controlli. On-model accetta un `mannequin_id` oltre a `face_angle`, `expression`, `lighting_style` e `frame_fit_style`.

  3. Passaggio 3

    Invia il job per gli occhiali tramite POST

    Esegui una POST su `/api/v1/eyewear-studio` con `eyewear_image` e i tuoi campi di styling. `background_prompt` accetta fino a 400 caratteri e sovrascrive `background_color`. Il polling è l'unico segnale di completamento — l'API non invia webhook.

  4. Passaggio 4

    Esegui il polling fino al completamento del job

    Esegui una GET su `/api/v1/eyewear-studio/:id` ogni 3 secondi finché `data.status` non diventa `completed` o `failed`; il completamento tipico richiede da 20 a 60 secondi.

  5. Passaggio 5

    Scarica e memorizza

    Il body completato contiene `output_url` e una miniatura. Salva il file sui tuoi server — considera l'URL come la consegna di un singolo job, non come un hosting permanente.

Domande che gli sviluppatori pongono prima di rilasciare scatti di occhiali

Cosa fa l'API eyewear studio?

Accetta una foto di prodotto di occhiali da vista o da sole e restituisce una fotografia rifinita — con le sole montature isolate in un trattamento studio, flat-lay, lifestyle o floating, oppure indossate sul volto di un modello AI a tua scelta.

Quanto costa uno scatto di occhiali?

5 credits a 2K e 6 credits a 4K, esattamente come il try-on di abbigliamento e gioielli. I job falliti vengono rimborsati automaticamente.

Qual è la differenza tra product-only e on-model?

`product-only` fotografa le montature da sole ed è gestito da `sub_tool`. `on-model` le posiziona sul volto di un modello AI ed è gestito da `mannequin_id`, `face_angle`, `expression`, `lighting_style` e `frame_fit_style`. I campi appartenenti all'altra modalità vengono ignorati.

Quali opzioni di styling espone ciascun sub-tool?

`studio-shot` accetta `backdrop` e `lighting`. `flat-lay` accetta `surface`, `arrangement_style` e `props`. `lifestyle` accetta `scene` e `mood`. `floating` accetta `angle` e `shadow_style`. Ciascuno di questi campi è un enum, quindi un valore imprevisto viene rifiutato anziché interpretato per approssimazione.

Posso usare il mio modello AI?

Sì. `mannequin_id` accetta qualsiasi id manichino da GET `/api/v1/eyewear-studio/mannequins`, e i manichini creati con l'API di generazione manichini possono essere usati allo stesso modo.

Come eseguo il polling per il risultato?

GET `/api/v1/eyewear-studio/:id` ogni 3 secondi finché `data.status` non è `completed` o `failed`. Non ci sono webhook; il polling è il segnale di completamento documentato.

Funzionalità correlate

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato

Prova l'API in 5 minuti

Genera una chiave API di Photta, incolla lo snippet cURL qui sopra e otterrai la tua prima immagine con modello prima ancora che il caffè sia pronto.

  • 20–60 sec
  • 5 credits a 2K · 6 credits a 4K
  • asincrono, polling
  • 600 richieste/min
  • Chiave Bearer