Yetenek · Gözlük stüdyosu

Gözlük sanal try-on API'si numaralı gözlükler ve güneş gözlükleri için

Tek cümlede

Photta'nın gözlük stüdyosu API'si, numaralı gözlük veya güneş gözlüğünün tek bir fotoğrafını işlenmiş bir çekime dönüştürür. Yalnızca ürün veya model üzerinde seçeneklerinden birini belirleyin, POST edin, her 3 saniyede bir polling yapın, durum completed olduğunda indirin. 2K çözünürlükte 5 credits.

  • Tipik süre: 20–60 sec
  • Credits: 2K'da 5 credits · 4K'da 6 credits
  • İşleme: asenkron, polling
  • Sınırlar: 600 istek/dk
  • Kimlik doğrulama: Bearer anahtarı

Bu sayfadaki her veri şuradan alınmıştır: Photta API dokümantasyonu · kontrol edildi

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
Örnek çıktı

Genel bakış

Genel bakış

Endpoint
POST /api/v1/eyewear-studio
Kimlik doğrulama
Bearer API anahtarı
İşleme
Asenkron — durum endpoint'ini sorgulayın (poll)
Tipik süre
20–60 sec
Credits
2K'da 5 credits · 4K'da 6 credits
En-boy oranları
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Girdi sınırları
Görsel başına en fazla 10 MB; JPEG, PNG, WebP
Idempotent
Hayır

İstek ve yanıt

İstek

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

İstek parametreleri

eyewear_image

Tür: stringZorunlu

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

mode

Tür: 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

Değerler: product-onlyon-model
sub_tool

Tür: 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

Değerler: studio-shotflat-laylifestylefloating
mannequin_id

Tür: 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

Tür: string

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

= front

Değerler: frontthree-quarterside-profile
expression

Tür: string

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

= neutral

Değerler: neutralsoft-smileseriousconfident
lighting_style

Tür: string

On-model only: how the portrait is lit.

= soft-diffused

Değerler: soft-diffusedstudionaturaldramatic
frame_fit_style

Tür: string

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

= casual

Değerler: casualprofessionalfashion-editorialsporty
backdrop

Tür: string

Studio-shot only: the backdrop behind the eyewear.

= white

Değerler: whitegrayblackgradient
lighting

Tür: string

Studio-shot only: the lighting setup.

= soft

Değerler: softharddramaticnatural
surface

Tür: string

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

= marble

Değerler: marblewoodfabricconcretemetal
arrangement_style

Tür: string

Flat-lay only: how the composition is arranged.

= minimal

Değerler: minimalsymmetricscatteredlayered
props

Tür: string

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

= none

Değerler: noneplantsaccessoriestech
scene

Tür: string

Lifestyle only: the real-world setting.

= coffee-shop

Değerler: coffee-shopbeachurban-streetofficepark
mood

Tür: string

Lifestyle only: the color mood of the scene.

= warm

Değerler: warmcoolvibrantmoody
angle

Tür: string

Floating only: the camera angle on the suspended frames.

= front

Değerler: frontthree-quartersidetop-down
shadow_style

Tür: string

Floating only: the shadow cast beneath the frames.

= soft-drop

Değerler: soft-dropnonehard-dropreflection
background_color

Tür: string

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

= white

Değerler: whitegrayblackbeige
background_prompt

Tür: string

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

aspect_ratio

Tür: string

Output aspect ratio.

= 3:4

Değerler: 3:41:14:39:1616:9
resolution

Tür: string

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

= 2K

Değerler: 2K4K

Hatalar

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.

Sınırlar

  • API anahtarı başına dakikada 600 istek (Sabit pencere; limit her planda aynıdır)
  • 429 yanıtı Retry-After: 30 saniye içerir
  • Görsel başına en fazla 10 MB
  • Formatlar: JPEG, PNG, WebP
  • Plan başına eşzamanlı toplu işlem: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Yalnızca polling — API webhook göndermez.

Tek bir çerçeve fotoğrafı girer, tek bir stillendirilmiş gözlük çekimi çıkar

Bir mod seçin, o modun sunduğu stili belirleyin, gönderin, polling yapın, indirin.

  1. Adım 1

    Bir API anahtarı oluşturun

    Gözlük stüdyosu, diğer tüm Photta yetenekleriyle aynı kimlik bilgilerini ve aynı kredi bakiyesini kullanır.

  2. Adım 2

    Bir mod ve stilini seçin

    `mode` değeri `product-only` veya `on-model` şeklindedir. Product-only modu bir `sub_tool` (`studio-shot`, `flat-lay`, `lifestyle` veya `floating`) alır ve bunların her biri kendi kontrollerini sunar. On-model modu ise `mannequin_id` ile birlikte `face_angle`, `expression`, `lighting_style` ve `frame_fit_style` parametrelerini alır.

  3. Adım 3

    Gözlük işini POST edin

    `eyewear_image` ve stil alanlarınızla `/api/v1/eyewear-studio` adresine POST isteği atın. `background_prompt` en fazla 400 karakter kabul eder ve `background_color` değerini geçersiz kılar. Tamamlanma durumunu öğrenmenin tek yolu polling'dir; API webhook göndermez.

  4. Adım 4

    İş tamamlanana kadar polling yapın

    `data.status` değeri `completed` veya `failed` olana kadar her 3 saniyede bir GET `/api/v1/eyewear-studio/:id` isteği atın; tipik tamamlanma süresi 20 ila 60 saniyedir.

  5. Adım 5

    İndirin ve kalıcı olarak saklayın

    Tamamlanan yanıt gövdesi `output_url` ve bir küçük resim içerir. Dosyayı kendiniz saklayın; URL'yi kalıcı bir barındırma olarak değil, tek bir işin teslimatı olarak değerlendirin.

Gözlük çekimlerini canlıya almadan önce geliştiricilerin sorduğu sorular

Gözlük stüdyosu API'si ne işe yarar?

Numaralı gözlük veya güneş gözlüğünün tek bir ürün fotoğrafını alır ve bunların stillendirilmiş bir fotoğrafını döndürür — çerçeveler ister stüdyo, flat-lay, lifestyle veya havada asılı konseptinde tek başına, ister seçtiğiniz bir yapay zeka modelinin yüzünde sunulur.

Bir gözlük çekiminin maliyeti nedir?

2K çözünürlükte 5 credits ve 4K çözünürlükte 6 credits; giyim ve takı try-on işlemleriyle aynıdır. Başarısız işlerin ücreti otomatik olarak iade edilir.

product-only ile on-model arasındaki fark nedir?

`product-only` çerçeveleri tek başlarına fotoğraflar ve `sub_tool` ile yönetilir. `on-model` ise çerçeveleri bir yapay zeka modelinin yüzüne yerleştirir; `mannequin_id`, `face_angle`, `expression`, `lighting_style` ve `frame_fit_style` ile kontrol edilir. Diğer moda ait alanlar yok sayılır.

Her bir alt araç hangi stil seçeneklerini sunar?

`studio-shot`, `backdrop` ve `lighting` parametrelerini alır. `flat-lay`, `surface`, `arrangement_style` ve `props` parametrelerini alır. `lifestyle`, `scene` ve `mood` parametrelerini alır. `floating`, `angle` ve `shadow_style` parametrelerini alır. Bu alanların her biri bir enum'dır, bu nedenle beklenmeyen bir değer tahmin edilmek yerine reddedilir.

Kendi AI modelimi kullanabilir miyim?

Evet. `mannequin_id`, GET `/api/v1/eyewear-studio/mannequins` endpoint'inden dönen herhangi bir manken kimliğini kabul eder; manken oluşturma API'si ile ürettiğiniz mankenler de aynı şekilde kullanılabilir.

Sonucu almak için nasıl polling yaparım?

`data.status` değeri `completed` veya `failed` olana kadar her 3 saniyede bir GET `/api/v1/eyewear-studio/:id` isteği atın. Webhook desteği yoktur; dokümante edilen tamamlanma sinyali polling'dir.

İlgili yetenekler

Bu sayfadaki her veri şuradan alınmıştır: Photta API dokümantasyonu · kontrol edildi

API'yi beş dakikada deneyin

Bir Photta API key oluşturun, yukarıdaki cURL kod parçacığını yapıştırın; kahveniz demlenmeden önce model üzerindeki ilk görselinizi alın.

  • 20–60 sec
  • 2K'da 5 credits · 4K'da 6 credits
  • asenkron, polling
  • 600 istek/dk
  • Bearer anahtarı