Início Rápido

Primeira imagem Photta em menos de cinco minutos.

Uma única conta, uma única chave de API, cinco comandos shell. Os passos abaixo seguem exatamente o recomendado pela documentação oficial da Photta — sem wrappers, sem SDKs, sem pressupostos de framework.

Em uma frase

Cadastre-se em ai.photta.app, clique em Gerar chave de API, exporte-a como PHOTTA_API_KEY, envie um POST para /api/v1/tryon/apparel e faça poll no ID de geração retornado a cada 3 segundos até o status mudar para completed — tipicamente entre 1.5 e 4 minutos.

Obter chave de API→Ler a documentação

Como funciona

Cinco comandos do zero à primeira imagem

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

01
Passo 1
Gerar uma chave de API
Cadastre-se em ai.photta.app e abra o dashboard de Desenvolvedores. Clique em Gerar chave de API — chaves live começam com photta_live_. Exporte-a para que o resto do tutorial possa lê-la do seu shell.
```
# Sign up at ai.photta.app, open the Developers dashboard,
# click "Generate API key" and copy it into your env.
export PHOTTA_API_KEY="photta_live_xxxxx"
export PHOTTA_BASE_URL="https://ai.photta.app/api/v1"
```

Passo 2

Envie seu primeiro provador virtual

Chame /api/v1/tryon/apparel com uma URL de imagem de produto, um ID de manequim e um ID de pose. A API responde 202 Accepted imediatamente e retorna um ID de geração em data.id.

curl -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_type": "dress",
    "product_images": ["https://example.com/dress.jpg"],
    "mannequin_id": "mnq_athena_ts",
    "pose_id": "pose_standing_front",
    "resolution": "2K",
    "aspect_ratio": "3:4"
  }'
# Response: 202 Accepted + data.id (generation ID)

Passo 3

Faça poll até completar

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

# Loop every 3 seconds until status flips to "completed".
# Typical completion: 1.5–4 minutes. Max 120 attempts = 6 min.
for i in $(seq 1 120); do
  RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" \
    -H "Authorization: Bearer $PHOTTA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "Job failed" && exit 1
  sleep 3
done

04
Passo 4
Persista o resultado
Quando o status mudar para completed, data.output_url conterá a imagem renderizada. Baixe os bytes para seu próprio storage para que seu produto não dependa do CDN da Photta para renderização.
```
# Pull the final URL out of the response and save the bytes.
OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url')
curl -sO "$OUTPUT_URL"
echo "Saved $(basename "$OUTPUT_URL")"
```

Passo 5

Trate os modos de falha honestamente

Faça o desvio com base no código de status HTTP: 402 para créditos insuficientes, 429 para rate limits (respeite o Retry-After), 5xx para erros transientes do servidor. Cada corpo de erro contém um error.code legível por máquina para sua lógica.

# Surface the common failure modes honestly.
case "$STATUS_CODE" in
  402) echo "Out of credits — top up at ai.photta.app" ;;
  429) echo "Rate limited — honour Retry-After header" ;;
  4??) echo "Client error: $(echo "$BODY" | jq '.error.message')" ;;
  5??) echo "Server error — retry with backoff" ;;
esac

Perguntas que outros desenvolvedores fazem

Perguntas sobre como começar

Quanto tempo leva o início rápido?+

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

Preciso de um 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 obter um maior saldo mensal de créditos e rate limits mais rápidos.

Qual endpoint devo testar primeiro?+

O provador de vestuário (/api/v1/tryon/apparel) — é o mais utilizado, a documentação é a mais completa e ele cobre o padrão assíncrono + polling que todos os outros endpoints da Photta reutilizam. Quando estiver confortável com ele, joias e manequim invisível funcionam da mesma forma.

Posso rodar pelo navegador?+

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

Início Rápido

Você está a cinco minutos da sua primeira imagem

Obter chave de API →Explorar a API