Recurso · Eyewear studio

API de try-on virtual de óculos para óculos de grau e de sol

Em uma frase

A API eyewear studio da Photta transforma uma foto de óculos de grau ou de sol em uma foto finalizada. Escolha apenas produto ou no modelo, faça o POST, faça polling a cada 3 segundos e baixe quando o status for completed. 5 credits em 2K.

Obter uma chave de API Ler a documentação

Tempo típico: 20–60 sec
Credits: 5 credits em 2K · 6 credits em 4K
Processamento: assíncrono, polling
Limites: 600 requisições/min
Autenticação: Chave Bearer

Todos os números nesta página vêm de a documentação da API da Photta · verificado 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 — Exemplo de saída

Visão geral

Endpoint: POST /api/v1/eyewear-studio
Autenticação: API key Bearer
Processamento: Assíncrono — faça polling no endpoint de status
Tempo típico: 20–60 sec
Credits: 5 credits em 2K · 6 credits em 4K
Proporções de tela: 3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limites de entrada: Até 10 MB por imagem; JPEG, PNG, WebP
Idempotente: Não

Requisição e resposta

Requisição

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 / Concluído

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

Parâmetros da requisição

CampoDescrição

eyewear_image

Tipo: stringObrigatório

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

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

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

frontthree-quarterside-profile

expression

Tipo: string

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

= neutral

neutralsoft-smileseriousconfident

lighting_style

Tipo: string

On-model only: how the portrait is lit.

= soft-diffused

soft-diffusedstudionaturaldramatic

frame_fit_style

Tipo: string

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

= casual

casualprofessionalfashion-editorialsporty

backdrop

Tipo: string

Studio-shot only: the backdrop behind the eyewear.

= white

whitegrayblackgradient

lighting

Tipo: string

Studio-shot only: the lighting setup.

= soft

softharddramaticnatural

surface

Tipo: string

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

= marble

marblewoodfabricconcretemetal

arrangement_style

Tipo: string

Flat-lay only: how the composition is arranged.

= minimal

minimalsymmetricscatteredlayered

props

Tipo: string

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

= none

noneplantsaccessoriestech

scene

Tipo: string

Lifestyle only: the real-world setting.

= coffee-shop

coffee-shopbeachurban-streetofficepark

mood

Tipo: string

Lifestyle only: the color mood of the scene.

= warm

warmcoolvibrantmoody

angle

Tipo: string

Floating only: the camera angle on the suspended frames.

= front

frontthree-quartersidetop-down

shadow_style

Tipo: string

Floating only: the shadow cast beneath the frames.

= soft-drop

soft-dropnonehard-dropreflection

background_color

Tipo: string

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

= white

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

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

2K4K

Erros

StatusTipoSignificado

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.

Limites

600 requisições por minuto por API key (Janela fixa; o limite é o mesmo em todos os planos)
Um 429 retorna Retry-After: 30 segundos
Até 10 MB por imagem
Formatos: JPEG, PNG, WebP
Batches concorrentes por plano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
Apenas polling — a API não envia webhooks.

Uma foto da armação entra, uma foto estilizada de óculos sai

Escolha um modo, selecione a estilização disponível para ele, envie, faça polling e baixe.

Passo 1
Gerar uma chave de API
O eyewear studio usa as mesmas credenciais e o mesmo saldo de credits que qualquer outro recurso da Photta.
Passo 2
Escolha um modo e sua estilização
`mode` pode ser `product-only` ou `on-model`. Product-only aceita um `sub_tool` — `studio-shot`, `flat-lay`, `lifestyle` ou `floating` — e cada um libera seus próprios controles. On-model aceita um `mannequin_id` além de `face_angle`, `expression`, `lighting_style` e `frame_fit_style`.
Passo 3
Envie o job de óculos via POST
Faça um POST para `/api/v1/eyewear-studio` com `eyewear_image` e seus campos de estilização. `background_prompt` aceita até 400 caracteres e sobrescreve `background_color`. Polling é o único sinal de conclusão — a API não envia webhooks.
Passo 4
Faça polling até a conclusão do job
Faça GET em `/api/v1/eyewear-studio/:id` a cada 3 segundos até que `data.status` seja `completed` ou `failed`; o tempo típico de conclusão é de 20 a 60 segundos.
Passo 5
Baixe e persista
O corpo da resposta concluída contém `output_url` e uma miniatura. Armazene o arquivo por conta própria — trate a URL como a entrega de um job, não como hospedagem permanente.

O mesmo endpoint em Node.js, Python e cURL

Dúvidas frequentes de desenvolvedores antes de colocar fotos de óculos em produção

O que a API eyewear studio faz?

Ela recebe uma foto de produto de óculos de grau ou de sol e retorna uma fotografia estilizada deles — seja apenas as armações em estúdio, flat-lay, lifestyle ou flutuante, seja usadas no rosto de um modelo de IA à sua escolha.

Quanto custa uma foto de óculos?

5 credits em 2K e 6 credits em 4K, o mesmo valor do try-on de roupas e joias. Jobs com falha são reembolsados automaticamente.

Qual é a diferença entre product-only e on-model?

`product-only` fotografa as armações sozinhas e é controlado por `sub_tool`. `on-model` coloca as armações no rosto de um modelo de IA e é controlado por `mannequin_id`, `face_angle`, `expression`, `lighting_style` e `frame_fit_style`. Campos que pertencem ao outro modo são ignorados.

Quais opções de estilização cada subferramenta expõe?

`studio-shot` aceita `backdrop` e `lighting`. `flat-lay` aceita `surface`, `arrangement_style` e `props`. `lifestyle` aceita `scene` e `mood`. `floating` aceita `angle` e `shadow_style`. Cada um desses campos é um enum, portanto valores inesperados são rejeitados em vez de inferidos.

Posso usar meu próprio modelo de IA?

Sim. `mannequin_id` aceita qualquer ID de manequim retornado por GET `/api/v1/eyewear-studio/mannequins`, e os manequins criados com a API de geração de manequins podem ser usados da mesma forma.

Como faço o polling pelo resultado?

Faça GET em `/api/v1/eyewear-studio/:id` a cada 3 segundos até que `data.status` seja `completed` ou `failed`. Não há webhooks; o polling é o sinal de conclusão documentado.

Recursos relacionados

Todos os números nesta página vêm de a documentação da API da Photta · verificado 2026-09-10

Experimente a API em cinco minutos

Gere uma chave de API do Photta, cole o snippet de cURL acima e você terá sua primeira imagem com modelo antes que o café termine de passar.

Criar uma conta e obter uma chave de API Ler a documentação

20–60 sec
5 credits em 2K · 6 credits em 4K
assíncrono, polling
600 requisições/min
Chave Bearer

API de try-on virtual de óculos para óculos de grau e de sol

Visão geral

Requisição e resposta

Parâmetros da requisição

Erros

Uma foto da armação entra, uma foto estilizada de óculos sai

Gerar uma chave de API

Escolha um modo e sua estilização

Envie o job de óculos via POST

Faça polling até a conclusão do job

Baixe e persista

O mesmo endpoint em Node.js, Python e cURL

Dúvidas frequentes de desenvolvedores antes de colocar fotos de óculos em produção

Recursos relacionados

Experimente a API em cinco minutos