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

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')

# $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'

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.

  1. 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_`.

  2. 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"
  3. 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"
  4. 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'
  5. 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

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.
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" ;;
esac

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.

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

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