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
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')const res = await fetch("https://api.photta.app/api/v1/eyewear-studio", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/eyewear-studio",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]
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')const res = await fetch("https://api.photta.app/api/v1/eyewear-studio", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/eyewear-studio",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "eyw_7a1c9e42f05b3d688c2e4f01a9d6b357",
"status": "completed",
"mode": "product-only",
"sub_tool": "studio-shot",
"output_url": "https://cdn.photta.app/generated/eyw_7a1c9e42f05b3d688c2e4f01a9d6b357.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/eyw_7a1c9e42f05b3d688c2e4f01a9d6b357-thumb.jpg",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 5,
"created_at": "2026-08-01T09:15:00Z",
"completed_at": "2026-08-01T09:15:38Z"
},
"request_id": "req_eyw002"
}Parametri della richiesta
eyewear_imageTipo: stringObbligatorio
The eyewear product image — glasses or sunglasses. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.
modeTipo: 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-modelsub_toolTipo: 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-laylifestylefloatingmannequin_idTipo: 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_angleTipo: string
On-model only: the angle of the model's face.
= front
Valori:frontthree-quarterside-profileexpressionTipo: string
On-model only: the model's facial expression.
= neutral
Valori:neutralsoft-smileseriousconfidentlighting_styleTipo: string
On-model only: how the portrait is lit.
= soft-diffused
Valori:soft-diffusedstudionaturaldramaticframe_fit_styleTipo: string
On-model only: the overall styling of how the frames are worn.
= casual
Valori:casualprofessionalfashion-editorialsportybackdropTipo: string
Studio-shot only: the backdrop behind the eyewear.
= white
Valori:whitegrayblackgradientlightingTipo: string
Studio-shot only: the lighting setup.
= soft
Valori:softharddramaticnaturalsurfaceTipo: string
Flat-lay only: the surface the eyewear lies on.
= marble
Valori:marblewoodfabricconcretemetalarrangement_styleTipo: string
Flat-lay only: how the composition is arranged.
= minimal
Valori:minimalsymmetricscatteredlayeredpropsTipo: string
Flat-lay only: complementary props placed around the eyewear.
= none
Valori:noneplantsaccessoriestechsceneTipo: string
Lifestyle only: the real-world setting.
= coffee-shop
Valori:coffee-shopbeachurban-streetofficeparkmoodTipo: string
Lifestyle only: the color mood of the scene.
= warm
Valori:warmcoolvibrantmoodyangleTipo: string
Floating only: the camera angle on the suspended frames.
= front
Valori:frontthree-quartersidetop-downshadow_styleTipo: string
Floating only: the shadow cast beneath the frames.
= soft-drop
Valori:soft-dropnonehard-dropreflectionbackground_colorTipo: string
Solid background color. Applies in both modes. Overridden by background_prompt when both are sent.
= white
Valori:whitegrayblackbeigebackground_promptTipo: string
Free-text background description. Max 400 characters — excess is silently truncated. Overrides background_color.
aspect_ratioTipo: string
Output aspect ratio.
= 3:4
Valori:3:41:14:39:1616:9resolutionTipo: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Valori:2K4K
Errori
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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.
Passaggio 1
Genera una chiave API
L'eyewear studio utilizza le stesse credenziali e lo stesso saldo di credits di ogni altra funzionalità Photta.
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`.
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.
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.
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.
Lo stesso endpoint in Node.js, Python e cURL
Node.js
API di try-on virtuale per occhiali in Node.js
Chiama aPI di try-on virtuale per occhiali di Photta da un backend Node.js con fetch nativo. Nessun SDK richiesto: salva la chiave, invia il job, esegui il polling per il risultato.
LeggiPython
API di try-on virtuale per occhiali in Python
Chiama la aPI di try-on virtuale per occhiali di Photta in Python con la libreria requests. Wrapper di trenta righe, compatibile con async tramite httpx, funziona in Django, FastAPI e Celery.
LeggicURL
API di try-on virtuale per occhiali con cURL
Chiama aPI di try-on virtuale per occhiali di Photta direttamente dalla shell con cURL. Invia, effettua il polling, scarica — ogni snippet si integra con jq per pipeline basate su script.
Leggi
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
Funzionalità
API di Virtual try-on per abbigliamento
REST API per applicare capi di abbigliamento su manichini AI. Generazione asincrona in 1.5–4 minuti, 5 crediti a 2K, 6 a 4K. Esempi per cURL, Node.js e Python.
Vedi l'endpointFunzionalità
API try-on per gioielli per collane, anelli, bracciali e orecchini
Applica collane, anelli, bracciali e orecchini su modelli AI tramite REST. 5 credits a 2K, manichini in primo piano integrati, rendering con gestione dei riflessi dalla documentazione di Photta.
Vedi l'endpointSviluppa
Crea un servizio di fotografia di prodotto basato su AI
La guida per i founder per rivendere l'API di virtual try-on di Photta come SaaS white-label: tenant key, fanout in batch, fatturazione per credits, realtà degli SLA.
Vedi l'endpointConfronta
Photta vs FASHN — API AI per la moda a confronto
Photta e FASHN a confronto: endpoint, costi in crediti, piani, limiti di concorrenza. Dati ricavati dalle rispettive pagine prezzi il 2026-04-19. Nessun numero inventato.
Vedi l'endpointGuida rapida
La prima immagine con Photta in meno di cinque minuti.
Registrati, genera una chiave API, esegui la tua prima chiamata cURL, fai polling fino al completamento, salva il risultato. Cinque passaggi, interamente documentati.
Vedi l'endpointRiferimento
Errori delle API di Photta
L'elenco completo dei tipi di errore delle API di Photta con i relativi codici di stato, la struttura del payload di errore e quali fallimenti ha senso riprovare.
Vedi l'endpointRiferimento
Rate limit delle API Photta
Il rate limit delle API Photta, la relativa finestra, l'header Retry-After, l'intervallo di polling e i limiti di concorrenza per piano, tutti desunti dalla documentazione delle API.
Vedi l'endpoint
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