cURL · API de try-on de joias
API de try-on de joias com cURL
Em uma frase
Exporte PHOTTA_API_KEY, faça um POST para https://api.photta.app/api/v1/api/v1/tryon/jewelry com o corpo JSON documentado, capture o ID de geração e, em seguida, faça um loop de GET em /api/v1/tryon/jewelry/{id} a cada 3 segundos até que data.status seja completed. Combine com jq para extrair a URL de saída.
- 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')
# $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/jewelry/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
STATUS=$(echo "$RESULT" | jq -r '.data.status')
[ "$STATUS" = "completed" ] && break
[ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'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.status
async function waitFor(id) {
for (let attempt = 0; attempt < 120; attempt++) {
const res = await fetch(`https://api.photta.app/api/v1/tryon/jewelry/${id}`, { headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` } });
const { data } = await res.json();
if (data.status === "completed") return data.output_url;
if (data.status === "failed") throw new Error(data.error_message ?? "generation failed");
await new Promise((r) => setTimeout(r, 3000));
}
throw new Error("timed out after 6 minutes");
}import 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"]
import time
def wait_for(job_id):
for _ in range(120):
res = requests.get(f"https://api.photta.app/api/v1/tryon/jewelry/{job_id}", headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"})
data = res.json()["data"]
if data["status"] == "completed":
return data["output_url"]
if data["status"] == "failed":
raise RuntimeError(data.get("error_message", "generation failed"))
time.sleep(3)
raise TimeoutError("timed out after 6 minutes")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
Como funciona
Cinco passos no shell, zero dependências além de curl e jq.
Passo 1
Cadastre-se e gere uma chave
Acesse ai.photta.app, abra a aba Developers e clique em Generate API key. As chaves de produção começam com `photta_live_`.
Passo 2
Exporte a chave
Adicione `export PHOTTA_API_KEY="photta_live_xxx"` ao perfil do seu shell ou a um arquivo `.envrc` para que todas as chamadas curl seguintes a utilizem automaticamente.
curl --version # macOS, Linux, WSL and Windows 10+ ship it export PHOTTA_API_KEY="photta_live_xxxxx"Passo 3
Defina a URL base fixa
`export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` mantém os comandos curl concisos.
export PHOTTA_BASE_URL="https://api.photta.app/api/v1" export AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"Passo 4
Envie e faça polling
Faça um POST para `$PHOTTA_BASE_URL/api/v1/tryon/jewelry` para obter um ID, depois execute `curl $PHOTTA_BASE_URL/api/v1/tryon/jewelry/{id}` em loop a cada 3 segundos. Faça um pipe da resposta para o jq para extrair `.data.status` de forma limpa.
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') # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed". for i in $(seq 1 120); do RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/jewelry/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY") STATUS=$(echo "$RESULT" | jq -r '.data.status') [ "$STATUS" = "completed" ] && break [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1 sleep 3 done echo "$RESULT" | jq -r '.data.output_url'Passo 5
Persista o resultado
Quando o job for concluído, extraia `.data.output_url` com o jq e use `curl -o` para gravar os bytes no armazenamento local — pronto para a próxima etapa da sua pipeline.
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.
case "$STATUS_CODE" in
402) echo "insufficient_credits_error — top up before retrying" ;;
429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
4??) echo "$BODY" | jq '.error.type, .error.message' ;;
5??) echo "api_error — retry with backoff" ;;
esacLimites
- 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.
Por que o cURL ainda é a maneira mais rápida de verificar uma API
- Zero instalação — o cURL já vem em todos os principais sistemas operacionais
- Combina com o jq para pipelines com scripts (CI, cron, hooks de shell)
- A maneira mais rápida de fazer um smoke test em um endpoint antes de integrá-lo ao código
- Todos os comandos desta página podem ser colados em qualquer shell POSIX
O que ele não faz
- O loop de polling bloqueia o terminal — migre para Node ou Python para ter workers paralelos
- O polling é o único sinal de conclusão; a API não envia webhooks
- Usuários do Prompt de Comando do Windows devem executar o WSL ou o curl.exe do PowerShell
Dúvidas frequentes de desenvolvedores
Existe uma ferramenta de CLI da Photta?
Ainda não — mas cURL com um wrapper bash de quinze linhas resolve a maior parte dos casos. A documentação prioriza exemplos em cURL porque qualquer linguagem pode executar um subprocesso, e o shell é o denominador comum em pipelines de CI.
Preciso do jq para usar a API?
Não estritamente — mas pipelines com scripts ficam muito mais fáceis com ele. O jq permite extrair `.data.id`, `.data.status` e `.data.output_url` da resposta JSON sem fazer parsing manual. Instale com `brew install jq` no macOS ou `apt install jq` no Debian/Ubuntu.
Como faço a autenticação com o curl?
Adicione `-H "Authorization: Bearer $PHOTTA_API_KEY"` a cada requisição. Mantenha a chave em uma variável de ambiente, nunca a insira diretamente em um script versionado. `curl --oauth2-bearer` também funciona, mas o header explícito é mais claro na documentação e nos logs.
Posso usar scripts baseados em curl em produção?
Para backfills em lote pontuais e cron jobs, sim — milhares de equipes executam backfills de catálogo dessa forma. Para uma aplicação de longa duração, uma linguagem convencional costuma ser melhor por oferecer tratamento de erros adequado, retries e observabilidade. Os exemplos em curl desta página continuam válidos mesmo após a migração para Node ou Python; a estrutura da requisição é a mesma.
Como faço polling a partir de um loop em bash?
Use `for i in $(seq 1 120); do … ; sleep 3; done` com a verificação de status no corpo do loop. Interrompa quando `.data.status` for `completed` ou `failed`. O exemplo de código nesta página mostra o padrão exato, incluindo um limite superior rígido para que um job travado não prenda o script indefinidamente.
Como leio respostas de erro no curl?
Use `curl -w "\n%{http_code}"` para capturar o código de status HTTP junto com o corpo JSON. Trate os retornos por status: 402 para credits insuficientes, 429 para rate limits (respeite o valor do Retry-After), 5xx para erros temporários do servidor. O corpo do erro sempre inclui os campos `error.code` e `error.message`.
Páginas relacionadas
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.
LerRecursos
API de try-on de joias para colares, anéis, pulseiras e brincos
Insira colares, anéis, pulseiras e brincos em modelos de IA via REST. 5 credits em 2K, manequins em close-up integrados, renderização sensível a reflexos direto da documentação da Photta.
LerConstruir
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.
LerIní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.
LerReferência
Preços da API Photta
Quanto custa em credits cada endpoint da Photta API em 2K e 4K, como funcionam as cobranças e reembolsos, e quais endpoints são gratuitos. Sem preço monetário por imagem.
Ler
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