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
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')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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."
},
)
data = res.json()["data"] # data["id"], data["status"]
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')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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."
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "jwl_a1b2c3",
"status": "completed",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"resolution": "2K",
"aspect_ratio": "3:4",
"output_url": "https://cdn.photta.app/generated/jwl_a1b2c3.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/jwl_a1b2c3-thumb.jpg",
"credits_used": 5,
"created_at": "2026-04-10T14:00:00Z",
"completed_at": "2026-04-10T14:01:10Z",
"duration_ms": 70000
},
"request_id": "req_jwl002"
}Parâmetros da requisição
jewelry_imageTipo: stringObrigatório
URL or base64 data URI of the jewelry product image.
jewelry_typeTipo: stringObrigatório
Type of jewelry.
Valores:necklaceearringsbraceletringmannequin_idTipo: 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.
backgroundTipo: 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.
resolutionTipo: 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:2K4Kaspect_ratioTipo: string
Output aspect ratio. 1:1 is not available at 4K resolution — that combination returns 400.
= 3:4
Valores:3:41:14:39:1616:9user_instructionTipo: 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
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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.
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.
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.
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.
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`.
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.
O mesmo endpoint em Node.js, Python e cURL
Node.js
API de try-on de joias em Node.js
Chame aPI de try-on de joias da Photta a partir de um backend em Node.js com fetch nativo. Nenhum SDK é necessário: armazene sua chave, envie o job e faça polling pelo resultado.
LerPython
API de try-on de joias em Python
Chame aPI de try-on de joias do Photta em Python com a biblioteca requests. Wrapper de trinta linhas, compatível com async via httpx, funciona em Django, FastAPI e Celery.
LercURL
API de try-on de joias com cURL
Chame a aPI de try-on de joias da Photta diretamente do shell com cURL. Envie, faça polling, baixe — todos os snippets funcionam com o jq para pipelines em script.
Ler
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
Recursos
API de try-on virtual para roupas
API REST que veste roupas em manequins de IA. Assíncrona, geração em 1.5–4 minutos, 5 credits em 2K, 6 em 4K. Exemplos em cURL, Node.js e Python.
Ver o endpointRecursos
API de manequim invisível para fotos de produtos em manequim invisível
Endpoint de IA para manequim invisível. Remova o manequim de uma foto de roupa e preserve os detalhes internos. 3D ou flat-lay, processamento em lote, 4 credits em 2K.
Ver o endpointConstruir
Crie um serviço de fotografia de produtos com IA
O playbook de um fundador para revender a API de virtual try-on da Photta como um SaaS white-label: chaves por tenant, fanout em lote, faturamento por credit, realidade de SLA.
Ver o endpointComparar
Photta vs FASHN — APIs de IA para moda, lado a lado
Photta e FASHN comparados: endpoints, preços em credits, planos, limites de concorrência. Dados obtidos da página de preços de cada empresa em 2026-04-19. Sem números inventados.
Ver o endpointComparar
Photta vs Ayna — API para desenvolvedores ou estúdio focado em Shopify
Photta vs Ayna comparados: três endpoints REST vs um estúdio focado em Shopify + API. Ambos têm pontos fortes. Obtido de cada site em 2026-04-19.
Ver o endpointInício rápido
Primeira imagem no Photta em menos de cinco minutos.
Cadastre-se, gere uma chave de API, execute sua primeira chamada cURL, faça polling até a conclusão, persista o resultado. Cinco etapas, documentadas de ponta a ponta.
Ver o endpointReferência
Erros da Photta API
A lista completa de tipos de erro da Photta API com seus status codes, o formato do corpo de erro e quais falhas valem a pena tentar novamente.
Ver o endpointReferência
Rate limits da API Photta
O rate limit da API Photta, sua janela, o header Retry-After, o intervalo de polling e os limites de simultaneidade por plano, tudo extraído da documentação da API.
Ver o endpoint
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