Ominaisuus · Silmälasistudio

Silmälasien virtuaalisen try-on-toiminnon API silmälaseille ja aurinkolaseille

Yhdellä lauseella

Phottan silmälasistudion API muuntaa yhden kuvan silmälaseista tai aurinkolaseista valmiiksi otokseksi. Valitse pelkkä tuote tai mallin päällä, tee POST-pyyntö, tee polling 3 sekunnin välein ja lataa kuva, kun tila on completed. 5 credits resoluutiolla 2K.

Hanki API-avain Lue dokumentaatio

Tyypillinen kesto: 20–60 sec
Credits: 5 credits resoluutiolla 2K · 6 credits resoluutiolla 4K
Käsittely: asynkroninen, polling
Rajoitukset: 600 pyyntöä/min
Autentikointi: Bearer-avain

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu 2026-09-10

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')

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.status

import 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"]

Sunglasses photographed by the eyewear studio API — Esimerkkitulos

Lyhyesti

Endpoint: POST /api/v1/eyewear-studio
Autentikointi: Bearer-API-avain
Käsittely: Asynkroninen — tee polling-kyselyitä status-endpointiin
Tyypillinen kesto: 20–60 sec
Credits: 5 credits resoluutiolla 2K · 6 credits resoluutiolla 4K
Kuvasuhteet: 3:4 · 1:1 · 4:3 · 9:16 · 16:9
Syöterajoitukset: Enintään 10 MB per kuva; JPEG, PNG, WebP
Idempotentti: Ei

Pyyntö ja vastaus

Pyyntö

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.status

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

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

Pyyntöparametrit

KenttäKuvaus

eyewear_image

Tyyppi: stringPakollinen

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

mode

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

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

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

Tyyppi: string

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

= front

frontthree-quarterside-profile

expression

Tyyppi: string

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

= neutral

neutralsoft-smileseriousconfident

lighting_style

Tyyppi: string

On-model only: how the portrait is lit.

= soft-diffused

soft-diffusedstudionaturaldramatic

frame_fit_style

Tyyppi: string

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

= casual

casualprofessionalfashion-editorialsporty

backdrop

Tyyppi: string

Studio-shot only: the backdrop behind the eyewear.

= white

whitegrayblackgradient

lighting

Tyyppi: string

Studio-shot only: the lighting setup.

= soft

softharddramaticnatural

surface

Tyyppi: string

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

= marble

marblewoodfabricconcretemetal

arrangement_style

Tyyppi: string

Flat-lay only: how the composition is arranged.

= minimal

minimalsymmetricscatteredlayered

props

Tyyppi: string

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

= none

noneplantsaccessoriestech

scene

Tyyppi: string

Lifestyle only: the real-world setting.

= coffee-shop

coffee-shopbeachurban-streetofficepark

mood

Tyyppi: string

Lifestyle only: the color mood of the scene.

= warm

warmcoolvibrantmoody

angle

Tyyppi: string

Floating only: the camera angle on the suspended frames.

= front

frontthree-quartersidetop-down

shadow_style

Tyyppi: string

Floating only: the shadow cast beneath the frames.

= soft-drop

soft-dropnonehard-dropreflection

background_color

Tyyppi: string

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

= white

whitegrayblackbeige

background_prompt

Tyyppi: string

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

aspect_ratio

Tyyppi: string

Output aspect ratio.

= 3:4

3:41:14:39:1616:9

resolution

Tyyppi: string

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

= 2K

2K4K

Virheet

TilaTyyppiMerkitys

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.

Rajoitukset

600 pyyntöä minuutissa per API-avain (Kiinteä aikaikkuna; rajoitus on sama kaikissa tilauksissa)
Vastaus 429 sisältää otsakkeen Retry-After: 30 sekuntia
Enintään 10 MB per kuva
Formaatit: JPEG, PNG, WebP
Rinnakkaiset eräajot per tilaus: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
Vain polling — API ei lähetä webhookeja.

Yksi kehyskuva sisään, yksi tyylitelty silmälasikuva ulos

Valitse tila, määritä tilan tarjoamat tyylittelyt, lähetä, tee polling, lataa.

Vaihe 1
Luo API-avain
Silmälasistudio käyttää samoja tunnistetietoja ja samaa credit-saldoa kuin kaikki muutkin Phottan ominaisuudet.
Vaihe 2
Valitse tila ja sen tyylittely
`mode` on `product-only` tai `on-model`. Product-only ottaa parametrina `sub_tool`-arvon — `studio-shot`, `flat-lay`, `lifestyle` tai `floating` — ja jokainen avaa omat säätönsä. On-model ottaa parametrina kentän `mannequin_id` sekä `face_angle`, `expression`, `lighting_style` ja `frame_fit_style`.
Vaihe 3
Tee silmälasityöstä POST-pyyntö
Tee POST-pyyntö polkuun `/api/v1/eyewear-studio` mukana `eyewear_image` ja tyylittelykenttäsi. `background_prompt` hyväksyy enintään 400 merkkiä ja ohittaa kentän `background_color`. Polling on ainoa valmistumissignaali — API ei lähetä webhookeja.
Vaihe 4
Tee pollingia, kunnes työ valmistuu
Tee GET-pyyntö polkuun `/api/v1/eyewear-studio/:id` 3 sekunnin välein, kunnes `data.status` on `completed` tai `failed`; tyypillinen valmistumisaika on 20–60 sekuntia.
Vaihe 5
Lataa ja tallenna pysyvästi
Valmistuneen vastauksen runko sisältää kentän `output_url` ja esikatselukuvan. Tallenna tiedosto itse — käsittele URL-osoitetta yhden työn toimituksena, älä pysyvänä säilytyspaikkana.

Sama endpoint ympäristöissä Node.js, Python ja cURL

Kysymykset, joita kehittäjät kysyvät ennen silmälasikuvien julkaisua

Mitä silmälasistudion API tekee?

Se ottaa vastaan yhden tuotekuvan silmälaseista tai aurinkolaseista ja palauttaa niistä tyylitellyn valokuvan — joko pelkät kehykset studio-, flat-lay-, lifestyle- tai leijuvana toteutuksena tai puettuna valitsemasi tekoälymallin kasvoille.

Paljonko silmälasikuva maksaa?

5 credits resoluutiolla 2K ja 6 credits resoluutiolla 4K, samoin kuin vaatteiden ja korujen try-on. Epäonnistuneet työt hyvitetään automaattisesti.

Mitä eroa on tiloilla product-only ja on-model?

`product-only` kuvaa kehykset sellaisenaan ja sitä ohjaa `sub_tool`. `on-model` asettaa ne tekoälymallin kasvoille ja sitä ohjaavat `mannequin_id`, `face_angle`, `expression`, `lighting_style` ja `frame_fit_style`. Toiseen tilaan kuuluvat kentät ohitetaan.

Mitä tyylittelyvaihtoehtoja kukin alityökalu tarjoaa?

`studio-shot` ottaa kentät `backdrop` ja `lighting`. `flat-lay` ottaa kentät `surface`, `arrangement_style` ja `props`. `lifestyle` ottaa kentät `scene` ja `mood`. `floating` ottaa kentät `angle` ja `shadow_style`. Jokainen näistä kentistä on enum, joten odottamaton arvo hylätään arvaamisen sijaan.

Voinko käyttää omaa tekoälymalliani?

Kyllä. `mannequin_id` hyväksyy minkä tahansa mallinuken tunnisteen kutsusta GET `/api/v1/eyewear-studio/mannequins`, ja mallinuken luonti-API:lla luotuja malleja voi käyttää samalla tavalla.

Miten kyselen (poll) tulosta?

Tee GET `/api/v1/eyewear-studio/:id` 3 sekunnin välein, kunnes `data.status` on `completed` tai `failed`. Webhookeja ei ole; polling on dokumentoitu valmistumissignaali.

Liittyvät ominaisuudet

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu 2026-09-10

Kokeile APIa viidessä minuutissa

Luo Photta-API-avain, liitä yllä oleva cURL-koodinpätkä, ja sinulla on ensimmäinen mallikuva ennen kuin kahvi ehtii tippua.

Luo tili ja hanki API-avain Lue dokumentaatio

20–60 sec
5 credits resoluutiolla 2K · 6 credits resoluutiolla 4K
asynkroninen, polling
600 pyyntöä/min
Bearer-avain

Silmälasien virtuaalisen try-on-toiminnon API silmälaseille ja aurinkolaseille

Lyhyesti

Pyyntö ja vastaus

Pyyntöparametrit

Virheet

Yksi kehyskuva sisään, yksi tyylitelty silmälasikuva ulos

Luo API-avain

Valitse tila ja sen tyylittely

Tee silmälasityöstä POST-pyyntö

Tee pollingia, kunnes työ valmistuu

Lataa ja tallenna pysyvästi

Sama endpoint ympäristöissä Node.js, Python ja cURL

Kysymykset, joita kehittäjät kysyvät ennen silmälasikuvien julkaisua

Liittyvät ominaisuudet

Kokeile APIa viidessä minuutissa