Recurso · Joias

API de try-on de joias para colares, anéis, pulseiras e brincos

Em uma frase

A API de try-on de joias da Photta recebe uma foto da joia, um jewelry_type (colar, anel, pulseira ou brincos) e um ID de manequim, retornando uma foto em close-up no modelo. Faça o POST, execute polling a cada 3 segundos e faça o download quando o status for completed.

  • Tempo típico: 1.5–4 min
  • 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

POST/api/v1/tryon/jewelry
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/jewelry \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
  "jewelry_type": "necklace",
  "mannequin_id": "mnk_j9k1l2",
  "background": "soft window light on dark velvet",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "Make the pendant 10% smaller."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
A necklace rendered on an AI model by the jewelry try-on API
Exemplo de saída

Visão geral

Visão geral

Endpoint
POST /api/v1/tryon/jewelry
Autenticação
API key Bearer
Processamento
Assíncrono — faça polling no endpoint de status
Tempo típico
1.5–4 min
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/tryon/jewelry \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
  "jewelry_type": "necklace",
  "mannequin_id": "mnk_j9k1l2",
  "background": "soft window light on dark velvet",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "Make the pendant 10% smaller."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Concluído

{
  "data": {
    "id": "jwl_a1b2c3",
    "status": "processing",
    "jewelry_type": "necklace",
    "mannequin_id": "mnk_j9k1l2",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-04-10T14:00:00Z"
  },
  "request_id": "req_jwl001"
}

Parâmetros da requisição

jewelry_image

Tipo: stringObrigatório

URL or base64 data URI of the jewelry product image.

jewelry_type

Tipo: stringObrigatório

Type of jewelry.

Valores: necklaceearringsbraceletring
mannequin_id

Tipo: stringObrigatório

ID of the mannequin. Must be jewelry-compatible and have a matching close-up view for the given jewelry_type. Use GET /api/v1/mannequins?jewelry_type=necklace to find compatible mannequins.

background

Tipo: string

Optional. Pass a URL or base64 data URI to use a reference photo as the scene; pass any other string to use it as a free-form text description (e.g. "soft window light on dark velvet"). When omitted, the original mannequin backdrop is preserved.

resolution

Tipo: string

Output resolution. "2K" costs 5 credits per image; "4K" costs 6 credits per image. 4K is produced natively in a single generation — pick it upfront; the resolution cannot be changed after creation. 4K cannot be combined with aspect_ratio 1:1 (returns 400).

= 2K

Valores: 2K4K
aspect_ratio

Tipo: string

Output aspect ratio. 1:1 is not available at 4K resolution — that combination returns 400.

= 3:4

Valores: 3:41:14:39:1616:9
user_instruction

Tipo: string

Free-form refinement, e.g. "make the pendant 10% smaller", "keep the clasp visible at the back of the neck". Capped at 400 characters server-side; longer strings are silently truncated. Requests to change the jewelry's size, scale, or proportions are honored and take priority; any other instruction applies only where it does not conflict with reproducing the jewelry exactly from the reference image. Not a determinism or seed control.

Erros

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.

O fluxo de vestuário, recalibrado para itens pequenos e altamente reflexivos

Escolha um manequim em close-up, envie, faça polling, baixe.

  1. Passo 1

    Gere uma chave de API

    Mesmo fluxo de vestuário — ai.photta.app → Developers → Generate API key. Uma chave funciona em todos os endpoints; um único saldo de credits cobre todas as capabilities.

  2. Passo 2

    Escolha um manequim em close-up

    Liste os manequins de joias ou envie o seu próprio com `POST /api/v1/mannequins/jewelry` — a Photta mantém um conjunto dedicado de manequins em close-up com texturas de pele calibradas para metais e pedras minúsculos.

  3. Passo 3

    Envie o job de joia via POST

    Faça um POST para `/api/v1/tryon/jewelry` com `jewelry_image`, `jewelry_type`, `mannequin_id` e os parâmetros opcionais `background`, `resolution` e `aspect_ratio`. O serviço ajusta automaticamente a escala e o posicionamento conforme a categoria da joia.

  4. Passo 4

    Faça polling até o job concluir

    GET `/api/v1/tryon/jewelry/:id` a cada 3 segundos. O formato da resposta é idêntico ao de vestuário — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. Passo 5

    Baixe e persista

    Enquadramento fechado 1:1 funciona melhor para miniaturas de PDP; proporções de tela mais amplas para editorial. Armazene os bytes por conta própria em vez de fazer hot-linking na CDN.

Perguntas que desenvolvedores fazem antes de colocar o try-on de joias em produção

Quais tipos de joias são suportados?

Quatro categorias explícitas: necklace, ring, bracelet, earrings. Cada categoria conta com seu próprio conjunto de manequins dedicados em close-up e uma heurística de posicionamento calibrada para esse formato. Anéis e brincos têm melhor resultado na proporção 1:1; colares ficam ótimos em 3:4.

Quanto custa um try-on de joia?

O mesmo que vestuário: 5 credits em 2K, 6 credits em 4K. Jobs com falha são reembolsados automaticamente. Sem custo adicional pela biblioteca de manequins em close-up.

Como o endpoint de joias se diferencia do de vestuário?

Mesma autenticação, mesmo padrão de polling, mesmo formato de resposta — as diferenças estão no corpo da requisição. Você envia `jewelry_type` e `jewelry_image` em vez de `product_type` e `product_images`, e seleciona manequins filtrados pela categoria da joia. Todo o restante (2K/4K, proporções de tela, credits) é compartilhado.

Posso enviar meu próprio modelo de joia?

Sim — `POST /api/v1/mannequins/jewelry` aceita uma referência personalizada em close-up, `POST /api/v1/mannequins/jewelry/generate` gera uma nova a partir de opções. Ambos retornam um ID que você insere de volta na requisição de try-on.

Como ele lida com metais reflexivos e pedras preciosas?

O pipeline de close-up processa metadados sobre destaques especulares e microgeometria. Ouro, prata e platina com polimento espelhado renderizam corretamente, sem o efeito fantasma ou a dispersão cromática gerados por pipelines genéricos de try-on. Fundos de estúdio ultra limpos são recomendados para obter os melhores resultados.

Como faço o polling do resultado?

GET `/api/v1/tryon/jewelry/:id` a cada 3 a 5 segundos. Mesmo ciclo de vida de status do vestuário: `processing` → `completed` ou `failed`. Uma janela de 1.5 a 4 minutos cobre a grande maioria dos jobs.

Capabilities relacionadas

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

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.

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