cURL · Virtual Try-On API

Virtual Try-On API con cURL

Il modo più rapido per capire un'API è chiamarla da terminale. La documentazione di Photta è cURL-first per scelta — tutto in questa pagina gira nel terminale senza Node o Python.

In una frase

Esporta PHOTTA_API_KEY, invia una POST a https://ai.photta.app/api/v1/tryon/apparel con il body JSON corretto, cattura l'ID generazione, poi esegui un loop curl … /tryon/apparel/:id ogni 3 secondi finché data.status diventa completed — solitamente tra 1.5 e 4 minuti. Usa jq per estrarre l'URL di output dalla risposta finale.

Aggiornato · 2026-04-19

La tua prima richiesta

cURLNode.jsPythoncURL
# Submit a try-on job. The API returns 202 Accepted + a generation ID.
JOB=$(curl -s -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -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"
  }')

ID=$(echo "$JOB" | jq -r '.data.id')
echo "Generation $ID queued"

# Poll every 3 seconds until the job completes (max 6 minutes).
for i in $(seq 1 120); do
  RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" -H "$AUTH_HEADER")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  if [ "$STATUS" = "completed" ]; then
    echo "$RESULT" | jq -r '.data.output_url'
    break
  fi
  if [ "$STATUS" = "failed" ]; then
    echo "$RESULT" | jq -r '.data.error_message' >&2
    exit 1
  fi
  sleep 3
done

Cosa aspettarsi

Typical completion

1.5–4min

2K / 4K credits

5 / 7

Aspect ratios

5

Product types

6

Come funziona

Virtual Try-On API con cURL

Cinque passaggi da shell, nessuna dipendenza oltre a curl e jq.

  1. 01

    Step 1

    Registrati e genera una chiave

    Vai su ai.photta.app, apri il tab Developers, clicca su Generate API key. Le chiavi live iniziano con photta_live_.

  2. 02

    Step 2

    Esporta la chiave

    Inserisci export PHOTTA_API_KEY="photta_live_xxx" nel profilo della tua shell o in un file .envrc per rendere automatica ogni chiamata curl successiva.

  3. 03

    Step 3

    Definisci l'URL di base

    export PHOTTA_BASE_URL="https://ai.photta.app/api/v1" mantiene i comandi curl brevi e facilita lo scambio con un URL sandbox quando disponibile.

  4. 04

    Step 4

    Invia e polling

    POST su $PHOTTA_BASE_URL/tryon/apparel per ottenere un ID, poi loop curl $PHOTTA_BASE_URL/tryon/apparel/$ID ogni 3 secondi. Passa la risposta a jq per estrarre .data.status in modo pulito.

  5. 05

    Step 5

    Salva il risultato

    Al termine del job, estrai .data.output_url con jq e usa curl -o per scaricare i byte localmente — pronti per il passaggio successivo della tua pipeline.

Codice, end to end

Copy, paste, done.

Four snippets — install prerequisites, wrap the REST call, submit + poll, then handle the errors that actually happen in production.

01cURL is already installed on macOS, Linux, WSL and modern Windows
bash
# Verify curl is available
curl --version

# Export your API key so the rest of the calls can reference it
export PHOTTA_API_KEY="photta_live_xxxxx"
02Set the base URL + auth header once
bash
# Pin the base URL in a shell variable so every call is a one-liner.
export PHOTTA_BASE_URL="https://ai.photta.app/api/v1"

# Reusable auth header — every request needs it.
AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"
03Submit and poll in one script
bash
# Submit a try-on job. The API returns 202 Accepted + a generation ID.
JOB=$(curl -s -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -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"
  }')

ID=$(echo "$JOB" | jq -r '.data.id')
echo "Generation $ID queued"

# Poll every 3 seconds until the job completes (max 6 minutes).
for i in $(seq 1 120); do
  RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" -H "$AUTH_HEADER")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  if [ "$STATUS" = "completed" ]; then
    echo "$RESULT" | jq -r '.data.output_url'
    break
  fi
  if [ "$STATUS" = "failed" ]; then
    echo "$RESULT" | jq -r '.data.error_message' >&2
    exit 1
  fi
  sleep 3
done
04Read the status code + error body instead of silently failing
bash
# -w pulls out the HTTP status without polluting the JSON body.
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{ "product_type": "dress" }')

BODY=$(echo "$RESPONSE" | sed '$d')
STATUS=$(echo "$RESPONSE" | tail -1)

case "$STATUS" in
  200|202)
    echo "$BODY" | jq '.data' ;;
  402)
    echo "Out of credits" ; echo "$BODY" | jq '.error' ;;
  429)
    RETRY=$(echo "$BODY" | jq -r '.error.retry_after')
    echo "Rate limited — retry in ${RETRY}s" ;;
  *)
    echo "Error $STATUS" ; echo "$BODY" | jq '.error' ;;
esac

Perché questa struttura

Perché cURL è ancora il modo più veloce per verificare un'API

  • Zero install — cURL ships with every major OS
  • Pairs with `jq` for scripted pipelines (CI, cron, bash hooks)
  • Ideal for smoke-testing endpoints before wiring them into code
  • All code in this page copy-pastes into any POSIX shell

Cosa non fa

Honest caveats

  • cURL's polling loop blocks your terminal — move to Node/Python for parallel workers
  • No streaming parser for the result; you fetch the final URL when the job is done
  • Windows Command Prompt users should run WSL or PowerShell's curl.exe wrapper

Domande frequenti degli sviluppatori

Questions other developers ask

Esiste un tool CLI di Photta?+

Non ancora — ma cURL più un wrapper bash di quindici righe fa quasi tutto il lavoro. La documentazione privilegia cURL perché ogni linguaggio può eseguire un sottoprocesso e la shell è il denominatore comune nelle pipeline CI.

Ho bisogno di jq per usare l'API?+

Non strettamente — ma le pipeline automatizzate sono molto più semplici con esso. jq ti permette di estrarre .data.id, .data.status e .data.output_url dal JSON senza parsing manuale. Installalo con brew install jq su macOS o apt install jq su Debian/Ubuntu.

Come mi autentico con curl?+

Aggiungi -H "Authorization: Bearer $PHOTTA_API_KEY" ad ogni richiesta. Tieni la chiave in una variabile d'ambiente, non scriverla mai negli script che carichi su Git. Anche curl --oauth2-bearer funziona, ma la forma con header esplicito è più chiara in documentazione e log.

Posso usare script basati su curl in produzione?+

Per backfill batch una-tantum e job cron, sì — molti team gestiscono l'aggiornamento dei cataloghi così. Per un'applicazione duratura, un linguaggio reale è preferibile per gestire meglio errori, retry e osservabilità. Gli esempi curl qui restano validi anche dopo il porting su Node o Python; la struttura della richiesta è la stessa.

Come effettuo il polling da un loop bash?+

Usa for i in $(seq 1 120); do … ; sleep 3; done con il controllo dello stato nel corpo del loop. Esci quando .data.status è completed o failed. L'esempio di codice in questa pagina mostra il pattern esatto, incluso un limite massimo per non bloccare lo script all'infinito.

Come leggo le risposte di errore in curl?+

Usa curl -w "\n%{http_code}" per catturare il codice di stato HTTP insieme al body JSON. Gestisci lo stato: 402 per crediti insufficienti, 429 per rate limit (rispetta il valore Retry-After), 5xx per errori temporanei del server. Il body di errore contiene sempre i campi error.code e error.message.

cURL · Virtual Try-On API

Crea un account e ottieni una API key

Esporta PHOTTA_API_KEY, invia una POST a https://ai.photta.app/api/v1/tryon/apparel con il body JSON corretto, cattura l'ID generazione, poi esegui un loop curl … /tryon/apparel/:id ogni 3 secondi finché data.status diventa completed — solitamente tra 1.5 e 4 minuti. Usa jq per estrarre l'URL di output dalla risposta finale.

Virtual Try-On API con cURL — Photta | Photta