Funktionalitet · Eyewear studio

API til virtuel try-on af briller til briller og solbriller

I én sætning

Phottas eyewear studio-API forvandler ét foto af briller eller solbriller til et færdigt billede. Vælg product-only eller on-model, send POST, udfør polling hvert 3. sekund, download når statussen er completed. 5 credits ved 2K.

  • Typisk tid: 20–60 sec
  • Credits: 5 credits ved 2K · 6 credits ved 4K
  • Behandling: async, polling
  • Grænser: 600 requests/min
  • Autentifikation: Bearer key

Hvert tal på denne side stammer fra Photta API-dokumentationen · tjekket

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
Eksempel på output

Kort fortalt

Kort fortalt

Endpoint
POST /api/v1/eyewear-studio
Autentifikation
Bearer API-nøgle
Behandling
Asynkron — poll status-endpointet
Typisk tid
20–60 sec
Credits
5 credits ved 2K · 6 credits ved 4K
Billedformater
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Inputgrænser
Op til 10 MB pr. billede; JPEG, PNG, WebP
Idempotent
Nej

Request og response

Request

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

Request-parametre

eyewear_image

Type: stringPåkrævet

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

mode

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

Værdier: product-onlyon-model
sub_tool

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

Værdier: studio-shotflat-laylifestylefloating
mannequin_id

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

Type: string

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

= front

Værdier: frontthree-quarterside-profile
expression

Type: string

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

= neutral

Værdier: neutralsoft-smileseriousconfident
lighting_style

Type: string

On-model only: how the portrait is lit.

= soft-diffused

Værdier: soft-diffusedstudionaturaldramatic
frame_fit_style

Type: string

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

= casual

Værdier: casualprofessionalfashion-editorialsporty
backdrop

Type: string

Studio-shot only: the backdrop behind the eyewear.

= white

Værdier: whitegrayblackgradient
lighting

Type: string

Studio-shot only: the lighting setup.

= soft

Værdier: softharddramaticnatural
surface

Type: string

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

= marble

Værdier: marblewoodfabricconcretemetal
arrangement_style

Type: string

Flat-lay only: how the composition is arranged.

= minimal

Værdier: minimalsymmetricscatteredlayered
props

Type: string

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

= none

Værdier: noneplantsaccessoriestech
scene

Type: string

Lifestyle only: the real-world setting.

= coffee-shop

Værdier: coffee-shopbeachurban-streetofficepark
mood

Type: string

Lifestyle only: the color mood of the scene.

= warm

Værdier: warmcoolvibrantmoody
angle

Type: string

Floating only: the camera angle on the suspended frames.

= front

Værdier: frontthree-quartersidetop-down
shadow_style

Type: string

Floating only: the shadow cast beneath the frames.

= soft-drop

Værdier: soft-dropnonehard-dropreflection
background_color

Type: string

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

= white

Værdier: whitegrayblackbeige
background_prompt

Type: string

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

aspect_ratio

Type: string

Output aspect ratio.

= 3:4

Værdier: 3:41:14:39:1616:9
resolution

Type: string

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

= 2K

Værdier: 2K4K

Fejl

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.

Grænser

  • 600 anmodninger i minuttet pr. API-nøgle (Fast vindue; grænsen er den samme på alle planer)
  • En 429 indeholder Retry-After: 30 sekunder
  • Op til 10 MB pr. billede
  • Formater: JPEG, PNG, WebP
  • Samtidige batches pr. plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Kun polling — API'et sender ingen webhooks.

Ét foto af brillestel ind, ét stylet brillebillede ud

Vælg en tilstand, vælg den styling tilstanden understøtter, indsend, udfør polling, download.

  1. Trin 1

    Generer en API-nøgle

    Eyewear studio bruger samme legitimationsoplysninger og samme credit-saldo som enhver anden Photta-funktionalitet.

  2. Trin 2

    Vælg en tilstand og dens styling

    `mode` er `product-only` eller `on-model`. Product-only tager et `sub_tool` — `studio-shot`, `flat-lay`, `lifestyle` eller `floating` — og hver åbner for sine egne kontroller. On-model tager et `mannequin_id` plus `face_angle`, `expression`, `lighting_style` og `frame_fit_style`.

  3. Trin 3

    POST eyewear-jobbet

    POST til `/api/v1/eyewear-studio` med `eyewear_image` og dine stylingfelter. `background_prompt` accepterer op til 400 tegn og tilsidesætter `background_color`. Polling er det eneste fuldførelsessignal — API'et sender ingen webhooks.

  4. Trin 4

    Udfør polling indtil jobbet er fuldført

    GET `/api/v1/eyewear-studio/:id` hvert 3. sekund indtil `data.status` er `completed` eller `failed`; typisk fuldførelse tager 20 til 60 sekunder.

  5. Trin 5

    Download og gem permanent

    Den fuldførte body indeholder `output_url` og et miniaturebillede. Gem selv filen — betragt URL'en som leveringen af ét job, ikke som permanent hosting.

Spørgsmål udviklere stiller før lancering af brillebilleder

Hvad gør eyewear studio-API'et?

Det tager ét produktfoto af briller eller solbriller og returnerer et stylet fotografi af dem — enten brillestellet alene i en studio-, flat-lay-, lifestyle- eller floating-opsætning, eller båret på ansigtet af en AI-model, du vælger.

Hvor meget koster et brillebillede?

5 credits ved 2K og 6 credits ved 4K, præcis som try-on til tøj og smykker. Fejlede jobs refunderes automatisk.

Hvad er forskellen på product-only og on-model?

`product-only` fotograferer brillestellet alene og styres via `sub_tool`. `on-model` placerer dem på en AI-models ansigt og styres af `mannequin_id`, `face_angle`, `expression`, `lighting_style` og `frame_fit_style`. Felter, der tilhører den anden tilstand, ignoreres.

Hvilke stylingmuligheder tilbyder de enkelte sub-tools?

`studio-shot` tager `backdrop` og `lighting`. `flat-lay` tager `surface`, `arrangement_style` og `props`. `lifestyle` tager `scene` og `mood`. `floating` tager `angle` og `shadow_style`. Hvert enkelt af disse felter er en enum, så en uventet værdi afvises frem for at blive gættet.

Kan jeg bruge min egen AI-model?

Ja. `mannequin_id` accepterer ethvert mannequin-id fra GET `/api/v1/eyewear-studio/mannequins`, og mannequiner, du bygger med mannequin-genererings-API'et, kan bruges på samme måde.

Hvordan poller jeg efter resultatet?

GET `/api/v1/eyewear-studio/:id` hvert 3. sekund, indtil `data.status` er `completed` eller `failed`. Der er ingen webhooks; polling er det dokumenterede signal for fuldførelse.

Relaterede funktionaliteter

Hvert tal på denne side stammer fra Photta API-dokumentationen · tjekket

Prøv API'et på fem minutter

Generér en Photta API-nøgle, indsæt cURL-kodestykket ovenfor, og du har dit første billede på en model, før kaffen er færdigbrygget.

  • 20–60 sec
  • 5 credits ved 2K · 6 credits ved 4K
  • async, polling
  • 600 requests/min
  • Bearer key