cURL · Ghost-Mannequin-API

Ghost-Mannequin-API mit cURL

In aller Kürze

Exportieren Sie PHOTTA_API_KEY, senden Sie einen POST an https://api.photta.app/api/v1/api/v1/ghost-mannequin mit dem dokumentierten JSON-Body, erfassen Sie die Generierungs-ID und führen Sie dann alle 3 Sekunden einen GET-Loop auf /api/v1/ghost-mannequin/{id} aus, bis data.status completed ist. Kombinieren Sie dies mit jq, um die Ausgabe-URL zu extrahieren.

  • Typische Dauer: 1.5–4 min
  • Credits: 4 Credits bei 2K · 5 Credits bei 4K
  • Verarbeitung: asynchron, Polling
  • Limits: 600 Anfragen/Min.
  • Authentifizierung: Bearer-Key

Jeder Zahlenwert auf dieser Seite stammt aus der Photta-API-Dokumentation · geprüft

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'

Auf einen Blick

Auf einen Blick

Endpoint
POST /api/v1/ghost-mannequin
Authentifizierung
Bearer-API-Schlüssel
Verarbeitung
Asynchron — Polling über den Status-Endpoint
Typische Dauer
1.5–4 min
Credits
4 Credits bei 2K · 5 Credits bei 4K
Seitenverhältnisse
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Eingabelimits
Bis zu 10 MB pro Bild; JPEG, PNG, WebP
Idempotent
Nein

Funktionsweise

Fünf Shell-Schritte, null Abhängigkeiten abgesehen von curl und jq.

  1. Schritt 1

    Registrieren und Schlüssel generieren

    Gehen Sie zu ai.photta.app, öffnen Sie den Reiter Developers und klicken Sie auf Generate API key. Live-Schlüssel beginnen mit `photta_live_`.

  2. Schritt 2

    Schlüssel exportieren

    Fügen Sie `export PHOTTA_API_KEY="photta_live_xxx"` in Ihr Shell-Profil oder eine `.envrc`-Datei ein, damit jeder nachfolgende curl-Aufruf ihn automatisch übernimmt.

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

    Basis-URL festlegen

    `export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` hält die curl-Befehle kurz.

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

    Absenden und pollen

    POST an `$PHOTTA_BASE_URL/api/v1/ghost-mannequin`, um eine ID zu erhalten, und führe dann alle 3 Sekunden `curl $PHOTTA_BASE_URL/api/v1/ghost-mannequin/{id}` in einer Schleife aus. Leite die Antwort per Pipe an jq weiter, um `.data.status` sauber zu extrahieren.

    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. Schritt 5

    Ergebnis persistieren

    Sobald der Job abgeschlossen ist, ziehe `.data.output_url` mit jq heraus und lade die Bytes mit `curl -o` in den lokalen Speicher — bereit für deinen nächsten Pipeline-Schritt.

Fehler

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

Limits

  • 600 Anfragen pro Minute pro API-Schlüssel (Festes Zeitfenster; das Limit ist in jedem Tarif identisch)
  • Ein 429 enthält Retry-After: 30 Sekunden
  • Bis zu 10 MB pro Bild
  • Formate: JPEG, PNG, WebP
  • Gleichzeitige Batches pro Tarif: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Nur Polling — die API sendet keine Webhooks.

Warum cURL immer noch der schnellste Weg ist, eine API zu verifizieren

  • Keine Installation nötig — cURL ist auf jedem gängigen Betriebssystem vorinstalliert
  • Ideal kombinierbar mit jq für geskriptete Pipelines (CI, Cron, Shell-Hooks)
  • Der schnellste Weg, einen Endpoint zu smoke-testen, bevor er in Code eingebunden wird
  • Jeder Befehl auf dieser Seite lässt sich direkt in jede POSIX-Shell einfügen

Was es nicht leistet

  • Die Polling-Schleife blockiert das Terminal — wechsle für parallele Worker zu Node oder Python
  • Polling ist das einzige Signal für den Abschluss; die API sendet keine Webhooks
  • Nutzer der Windows-Eingabeaufforderung sollten WSL oder PowerShells curl.exe verwenden

Häufige Fragen von Entwicklern

Gibt es ein Photta-CLI-Tool?

Noch nicht — aber cURL plus ein 15-zeiliger Bash-Wrapper decken das meiste ab. Die Dokumentation priorisiert cURL-Beispiele, da jede Sprache Subprozesse ausführen kann und die Shell der gemeinsame Nenner in CI-Pipelines ist.

Brauche ich jq, um die API zu nutzen?

Nicht zwingend — aber geskriptete Pipelines sind damit deutlich einfacher. Mit jq ziehst du `.data.id`, `.data.status` und `.data.output_url` aus der JSON-Antwort heraus, ohne sie manuell parsen zu müssen. Installation via `brew install jq` unter macOS oder `apt install jq` unter Debian/Ubuntu.

Wie authentifiziere ich mich mit curl?

Füge jedem Request `-H "Authorization: Bearer $PHOTTA_API_KEY"` hinzu. Behalte den Key in einer Umgebungsvariable und schreibe ihn niemals direkt in ein Skript, das du committest. `curl --oauth2-bearer` funktioniert ebenfalls, aber die explizite Header-Form ist in Dokumentationen und Logs übersichtlicher.

Kann ich curl-basierte Skripte in der Produktion nutzen?

Für einmalige Batch-Backfills und Cron-Jobs: Ja — Tausende von Teams führen Katalog-Backfills auf diese Weise durch. Für eine langlebige Anwendung ist eine richtige Programmiersprache meist besser, da du sauberes Error-Handling, Retries und Observability erhältst. Die curl-Beispiele auf dieser Seite bleiben auch nach der Portierung auf Node oder Python gültig; die Request-Struktur ist identisch.

Wie polle ich aus einer Bash-Schleife?

Verwende `for i in $(seq 1 120); do … ; sleep 3; done` mit dem Status-Check im Schleifenkörper. Brich ab, sobald `.data.status` `completed` oder `failed` ist. Das Codebeispiel auf dieser Seite zeigt das genaue Pattern, einschließlich einer festen Obergrenze, damit ein hängender Job das Skript nicht endlos blockiert.

Wie lese ich Fehlerantworten in curl aus?

Verwende `curl -w "\n%{http_code}"`, um den HTTP-Statuscode zusammen mit dem JSON-Body abzufangen. Verzweige anhand des Status: 402 bei unzureichenden Credits, 429 bei Rate Limits (beachte den Retry-After-Wert), 5xx bei transienten Serverfehlern. Der Fehler-Body enthält immer die Felder `error.code` und `error.message`.

Testen Sie die API in fünf Minuten

Generieren Sie einen Photta-API-Schlüssel, fügen Sie das obige cURL-Snippet ein, und Sie erhalten Ihr erstes Bild am Model, noch bevor der Kaffee fertig gebrüht ist.

  • 1.5–4 min
  • 4 Credits bei 2K · 5 Credits bei 4K
  • asynchron, Polling
  • 600 Anfragen/Min.
  • Bearer-Key