cURL · API Ghost mannequin

API Ghost mannequin con cURL

In sintesi

Esporta PHOTTA_API_KEY, invia una POST a https://api.photta.app/api/v1/api/v1/ghost-mannequin con il body JSON documentato, acquisisci l'ID di generazione, quindi esegui ciclicamente una GET su /api/v1/ghost-mannequin/{id} ogni 3 secondi finché data.status non è completed. Abbinalo a jq per estrarre l'URL di output.

  • Tempo tipico: 1.5–4 min
  • Credits: 4 credits a 2K · 5 credits a 4K
  • Elaborazione: asincrono, polling
  • Limiti: 600 richieste/min
  • Autenticazione: Chiave Bearer

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

POST/api/v1/ghost-mannequin
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

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

Panoramica

Panoramica

Endpoint
POST /api/v1/ghost-mannequin
Autenticazione
API key Bearer
Elaborazione
Asincrona — effettua il polling dell'endpoint di stato
Tempo tipico
1.5–4 min
Credits
4 credits a 2K · 5 credits a 4K
Rapporti d'aspetto
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limiti di input
Fino a 10 MB per immagine; JPEG, PNG, WebP
Idempotente
No

Come funziona

Cinque passaggi da shell, zero dipendenze oltre a curl e jq.

  1. Passaggio 1

    Registrati e genera una chiave

    Vai su ai.photta.app, apri la scheda Developers, fai clic su Generate API key. Le chiavi live iniziano con `photta_live_`.

  2. Passaggio 2

    Esporta la chiave

    Inserisci `export PHOTTA_API_KEY="photta_live_xxx"` nel profilo della tua shell o in un file `.envrc` in modo che ogni successiva chiamata curl la rilevi automaticamente.

    curl --version   # macOS, Linux, WSL and Windows 10+ ship it
    export PHOTTA_API_KEY="photta_live_xxxxx"
  3. Passaggio 3

    Fissa l'URL di base

    `export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` mantiene brevi i comandi curl.

    export PHOTTA_BASE_URL="https://api.photta.app/api/v1"
    export AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"
  4. Passaggio 4

    Invia ed esegui il polling

    Invia una POST a `$PHOTTA_BASE_URL/api/v1/ghost-mannequin` per ottenere un ID, quindi esegui un ciclo con `curl $PHOTTA_BASE_URL/api/v1/ghost-mannequin/{id}` ogni 3 secondi. Passa la risposta a jq tramite pipe per estrarre `.data.status` in modo pulito.

    RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
      -H "Authorization: Bearer $PHOTTA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
      "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front",
      "angle": "side",
      "style": "3d",
      "background_color": "white",
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "user_instruction": "closed front, cream interior lining",
      "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
    }')
    ID=$(echo "$RESPONSE" | jq -r '.data.id')
    
    # $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/ghost-mannequin/$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'
  5. Passaggio 5

    Salva il risultato

    Quando il job viene completato, estrai `.data.output_url` con jq e usa `curl -o` per salvare i byte nello storage locale — pronto per il passaggio successivo della pipeline.

Errori

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred. Retry later.
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

Limiti

  • 600 richieste al minuto per API key (Finestra fissa; il limite è lo stesso per ogni piano)
  • Un 429 restituisce Retry-After: 30 secondi
  • Fino a 10 MB per immagine
  • Formati: JPEG, PNG, WebP
  • Batch simultanei per piano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Solo polling — l'API non invia webhook.

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

  • Nessuna installazione — cURL è incluso in tutti i principali sistemi operativi
  • Si integra perfettamente con jq per pipeline basate su script (CI, cron, shell hook)
  • Il modo più rapido per fare smoke testing su un endpoint prima di integrarlo nel codice
  • Ogni comando in questa pagina può essere incollato in qualsiasi shell POSIX

Cosa non fa

  • Il ciclo di polling blocca il terminale — passa a Node o Python per worker paralleli
  • Il polling è l'unico segnale di completamento; l'API non invia webhook
  • Gli utenti del Prompt dei comandi di Windows dovrebbero usare WSL o curl.exe di PowerShell

Domande frequenti degli sviluppatori

Esiste uno strumento CLI di Photta?

Non ancora — ma cURL combinato con uno script bash di quindici righe risolve gran parte delle esigenze. La documentazione dà priorità a esempi basati su cURL perché ogni linguaggio può eseguire un sottoprocesso, e la shell è il denominatore comune nelle pipeline CI.

Serve jq per usare l'API?

Non strettamente — ma le pipeline basate su script risultano molto più semplici. jq consente di estrarre `.data.id`, `.data.status` e `.data.output_url` dalla risposta JSON senza doverne fare il parsing a mano. Installalo con `brew install jq` su macOS o `apt install jq` su Debian/Ubuntu.

Come si effettua l'autenticazione con curl?

Aggiungi `-H "Authorization: Bearer $PHOTTA_API_KEY"` a ogni richiesta. Mantieni la chiave in una variabile d'ambiente, senza mai inserirla inline in uno script sottoposto a commit. Funziona anche `curl --oauth2-bearer`, ma la forma con header esplicito è più chiara nella documentazione e nei log.

Posso usare script basati su curl in produzione?

Per backfill batch una tantum e job cron, sì — migliaia di team gestiscono il backfill dei cataloghi in questo modo. Per un'applicazione a lungo termine, un vero linguaggio di programmazione è generalmente preferibile per disporre di corretta gestione degli errori, retry e osservabilità. Gli esempi curl su questa pagina rimangono validi anche dopo il porting su Node o Python; la struttura della richiesta è identica.

Come si esegue il polling da un ciclo bash?

Usa `for i in $(seq 1 120); do … ; sleep 3; done` con il controllo dello stato nel corpo del ciclo. Interrompi quando `.data.status` è `completed` o `failed`. Il frammento di codice in questa pagina mostra il pattern esatto, incluso un limite massimo rigido affinché un job bloccato non mantenga lo script in sospeso all'infinito.

Come si leggono le risposte di errore in curl?

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

Pagine correlate

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

Prova l'API in 5 minuti

Genera una chiave API di Photta, incolla lo snippet cURL qui sopra e otterrai la tua prima immagine con modello prima ancora che il caffè sia pronto.

  • 1.5–4 min
  • 4 credits a 2K · 5 credits a 4K
  • asincrono, polling
  • 600 richieste/min
  • Chiave Bearer