Guia rápido

Primeira imagem no Photta em menos de cinco minutos.

Em uma frase

Cadastre-se em ai.photta.app, clique em Generate API key, exporte-a como PHOTTA_API_KEY, faça um POST para /api/v1/tryon/apparel e faça polling do generation ID retornado a cada 3 segundos até que o status mude para completed — normalmente entre 1.5 e 4 minutos.

Obter uma chave de APILer a documentação
  • Autenticação: Chave Bearer
  • Processamento: assíncrono, polling
  • Limites: 600 requisições/min

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/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

Como funciona

Cinco comandos do zero à primeira imagem

Cole-os em um terminal nesta ordem. Cada snippet é independente e utiliza apenas curl + jq.

  1. Passo 1

    Gere uma chave de API

    Cadastre-se em ai.photta.app e acerte o painel de Developers. Clique em Generate API key — chaves ativas começam com photta_live_. Exporte-a para que o restante do guia possa lê-la a partir do seu shell.

    # https://ai.photta.app → Developers → Generate API key
export PHOTTA_API_KEY="photta_live_xxxxx"
export PHOTTA_BASE_URL="https://api.photta.app/api/v1"

  2. Passo 2

    Envie seu primeiro POST de try-on

    Chame /api/v1/tryon/apparel com a URL da imagem do produto e um ID de manequim. A API responde imediatamente com 202 Accepted e retorna um generation ID em data.id.

    RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

  3. Passo 3

    Faça polling até a conclusão

    GET /api/v1/tryon/apparel/:id a cada 3 segundos. A conclusão típica leva de 1.5 a 4 minutos. Defina um limite máximo de tentativas para que um job travado não prenda seu script indefinidamente.

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

  4. Passo 4

    Persista a saída

    Quando o status mudar para completed, data.output_url conterá a imagem renderizada. Baixe os bytes no seu próprio storage para que seu produto não dependa da CDN da Photta para renderização.

    OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url')
curl -sO "$OUTPUT_URL"
echo "Saved $(basename "$OUTPUT_URL")"

  5. Passo 5

    Trate os modos de falha de forma explícita

    Faça o desvio pelo código de status HTTP: 402 para créditos insuficientes, 429 para rate limits (respeite o Retry-After), 5xx para erros transientes do servidor. O corpo de cada erro traz um error.code legível por máquina para você tratar.

    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

Dúvidas frequentes de desenvolvedores

Dúvidas sobre os primeiros passos

Quanto tempo leva o quickstart?

Cinco minutos para cadastro + geração de chave + primeiro cURL. A geração em si leva de 1.5 a 4 minutos, então planeje dez minutos de tempo real antes de ver sua primeira imagem no modelo.

Preciso de cartão de crédito para testar?

Novas contas vêm com créditos de teste que você pode usar antes de pagar. Quando estiver pronto para entrar em produção, assine um plano para ter um saldo mensal de créditos maior e rate limits mais altos.

Qual endpoint devo testar primeiro?

Apparel try-on (/api/v1/tryon/apparel) — é o mais utilizado, a documentação é a mais completa e cobre o padrão de async + polling que todos os outros endpoints da Photta reutilizam. Quando dominar este, jewelry e ghost mannequin funcionam da mesma forma.

Posso rodar a partir do navegador?

Não. Sua chave de API deve permanecer no lado do servidor — enviá-la para o navegador expõe sua credencial a qualquer visitante. Encaminhe as chamadas através de um proxy leve no seu próprio backend (route handler do Next.js, Express, Flask, Lambda) e faça o navegador se comunicar com o seu proxy.

Páginas relacionadas

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

Você está a cinco minutos da sua primeira imagem

Obter uma chave de APIExplorar a API
  • Chave Bearer
  • assíncrono, polling
  • 600 requisições/min