Guida rapida

La prima immagine con Photta in meno di cinque minuti.

In sintesi

Registrati su ai.photta.app, fai clic su Generate API key, esportala come PHOTTA_API_KEY, invia una POST a /api/v1/tryon/apparel ed esegui il polling dell'ID di generazione restituito ogni 3 secondi fino a quando lo stato non diventa completed — generalmente entro 1.5 - 4 minuti.

Ottieni una chiave APILeggi la documentazione
  • Autenticazione: Chiave Bearer
  • Elaborazione: asincrono, polling
  • Limiti: 600 richieste/min

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato 

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

Come funziona

Cinque comandi da zero alla prima immagine

Incollali in un terminale in sequenza. Ogni snippet è autonomo e richiede solo curl + jq.

  1. Passaggio 1

    Genera una chiave API

    Registrati su ai.photta.app e apri la dashboard Developers. Fai clic su Generate API key — le chiavi live iniziano con photta_live_. Esportala in modo che il resto della guida possa leggerla dalla 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. Passaggio 2

    Esegui la prima POST di try-on

    Invia una richiesta a /api/v1/tryon/apparel con l'URL dell'immagine del prodotto e un ID del manichino. L'API risponde immediatamente con 202 Accepted e restituisce un ID di generazione in 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. Passaggio 3

    Esegui il polling fino al completamento

    GET /api/v1/tryon/apparel/:id ogni 3 secondi. Il completamento tipico richiede 1.5–4 minuti. Imposta un limite massimo ai tentativi per evitare che un job bloccato blocchi il tuo script all'infinito.

    # $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. Passaggio 4

    Salva l'output in modo persistente

    Quando lo stato passa a completed, data.output_url contiene l'immagine renderizzata. Scarica i byte nel tuo storage in modo che il tuo prodotto non dipenda dal CDN di Photta per il rendering.

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

  5. Passaggio 5

    Gestisci le modalità di errore in modo rigoroso

    Crea rami condizionali in base al codice di stato HTTP: 402 per credits insufficienti, 429 per i rate limit (rispetta l'header Retry-After), 5xx per errori temporanei del server. Ogni payload di errore include un error.code machine-readable su cui puoi basare la tua logica.

    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

Domande frequenti degli sviluppatori

Domande sui primi passi

Quanto dura il quickstart?

Cinque minuti per registrazione + generazione della chiave + prima richiesta cURL. La generazione vera e propria richiede da 1.5 a 4 minuti; pianifica quindi una decina di minuti reali prima di vedere la tua prima immagine con modello indosso.

Serve una carta di credito per provarlo?

I nuovi account includono credits di prova da utilizzare prima di effettuare pagamenti. Quando sarai pronto per la produzione, sottoscrivi un piano per ottenere un saldo mensile di credits più elevato e rate limit più veloci.

Quale endpoint dovrei provare per primo?

Apparel try-on (/api/v1/tryon/apparel) — è il più utilizzato, ha la documentazione più completa e copre il pattern asincrono con polling riutilizzato da ogni altro endpoint Photta. Una volta acquisita familiarità, jewelry e ghost mannequin funzionano nello stesso modo.

Posso eseguirlo direttamente dal browser?

No. La tua API key deve rimanere lato server — inviarla al browser significa esporla a tutti i visitatori. Instrada le chiamate attraverso un proxy leggero sul tuo backend (Next.js route handler, Express, Flask, Lambda) e fai comunicare il browser esclusivamente con il tuo proxy.

Pagine correlate

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato

Sei a cinque minuti dalla tua prima immagine

Ottieni una chiave APIEsplora l'API
  • Chiave Bearer
  • asincrono, polling
  • 600 richieste/min