Quickstart

Prima immagine Photta in meno di cinque minuti.

Un solo account, una sola API key, cinque comandi shell. I passaggi seguenti corrispondono esattamente a quanto raccomandato dalla documentazione ufficiale — senza wrapper, SDK o assunzioni di framework.

In una frase

Registrati su ai.photta.app, clicca su Generate API key, esportala come PHOTTA_API_KEY, invia una POST a /api/v1/tryon/apparel e polling dell'ID generazione restituito ogni 3 secondi finché status diventa completed — solitamente tra 1.5 e 4 minuti.

Ottieni una API key→Leggi la documentazione

Come funziona

Cinque comandi da zero alla prima immagine

Incollali in ordine nel terminale. Ogni snippet è autosufficiente e usa solo curl + jq.

01
Step 1
Genera una API key
Registrati su ai.photta.app e apri la dashboard Developers. Clicca su Generate API key — le chiavi live iniziano con photta_live_. Esportala per permettere alla guida di leggerla dalla 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"
```

Step 2

Invia il tuo primo try-on tramite POST

Chiama /api/v1/tryon/apparel con l'URL di un'immagine prodotto, un ID manichino e un ID posa. L'API risponde immediatamente 202 Accepted e restituisce un ID generazione in 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)

Step 3

Polling fino al termine

GET /api/v1/tryon/apparel/:id ogni 3 secondi. Il completamento tipico è 1.5–4 minuti. Imposta un limite massimo di tentativi per non bloccare lo script.

# 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

Step 4

Salva l'output

Quando status diventa completed, data.output_url contiene l'immagine renderizzata. Scarica i byte nel tuo storage per non dipendere dalla CDN di Photta.

# 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")"

Step 5

Gestisci gli errori in modo onesto

Verifica il codice di stato HTTP: 402 per crediti insufficienti, 429 per rate limit (rispetta Retry-After), 5xx per errori temporanei. Ogni body di errore include un error.code leggibile programmaticamente.

# 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

Domande frequenti degli sviluppatori

Domande sul primo avvio

Quanto tempo richiede il quickstart?+

Cinque minuti per registrazione, generazione chiave e primo cURL. La generazione stessa richiede da 1.5 a 4 minuti, quindi prevedi dieci minuti totali prima di vedere la prima immagine.

Serve una carta di credito per provare?+

I nuovi account includono crediti di prova gratuiti. Quando sarai pronto per la produzione, potrai sottoscrivere un piano per aumentare il saldo crediti mensile e i rate limit.

Quale endpoint dovrei provare per primo?+

Il try-on abbigliamento (/api/v1/tryon/apparel) — è il più utilizzato, la documentazione è completa e copre il pattern async + polling riutilizzato da tutti gli altri endpoint Photta. Una volta compreso questo, gioielli e ghost mannequin funzionano allo stesso modo.

Posso eseguirlo dal browser?+

No. La tua API key deve rimanere lato server — esporla nel browser significa renderla pubblica. Invia le chiamate tramite un proxy nel tuo backend (Next.js route handler, Express, Flask, Lambda) e fai comunicare il browser con il tuo proxy.