Quickstart

Erstes Photta-Bild in unter 5 Minuten.

In aller Kürze

Registriere dich auf ai.photta.app, klicke auf „Generate API key“, exportiere ihn als PHOTTA_API_KEY, sende einen POST an /api/v1/tryon/apparel und polle die zurückgegebene Generierungs-ID alle 3 Sekunden, bis der Status auf completed wechselt — typischerweise innerhalb von 1.5 bis 4 Minuten.

API-Key anfordernDokumentation lesen
  • Authentifizierung: Bearer-Key
  • Verarbeitung: asynchron, Polling
  • Limits: 600 Anfragen/Min.

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

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

Funktionsweise

5 Befehle von null bis zum ersten Bild

Füge sie der Reihe nach in ein Terminal ein. Jedes Snippet ist in sich geschlossen und benötigt nur curl + jq.

  1. Schritt 1

    API-Key generieren

    Registriere dich auf ai.photta.app und öffne das Developers-Dashboard. Klicke auf „Generate API key“ — Live-Keys beginnen mit photta_live_. Exportiere ihn, damit der Rest des Leitfadens ihn aus deiner Shell auslesen kann.

    # 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. Schritt 2

    Erstes try-on per POST absenden

    Rufe /api/v1/tryon/apparel mit einer Produktbild-URL und einer Mannequin-ID auf. Die API antwortet sofort mit 202 Accepted und gibt eine Generierungs-ID in data.id zurück.

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

    Pollen bis zum Abschluss

    GET /api/v1/tryon/apparel/:id alle 3 Sekunden. Typische Fertigstellung dauert 1.5–4 Minuten. Setze ein oberes Limit für Versuche, damit ein hängender Job dein Skript nicht endlos blockiert.

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

    Output persistieren

    Sobald der Status auf completed wechselt, enthält data.output_url das gerenderte Bild. Lade die Bytes in deinen eigenen Speicher herunter, damit dein Produkt beim Rendern nicht vom CDN von Photta abhängt.

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

  5. Schritt 5

    Fehlerfälle sauber behandeln

    Verzweige nach HTTP-Statuscode: 402 für unzureichende credits, 429 für Rate Limits (Retry-After beachten), 5xx für temporäre Serverfehler. Jeder Error-Body enthält einen maschinenlesbaren error.code, auf den du reagieren kannst.

    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

Häufige Fragen von Entwicklern

Fragen zum Einstieg

Wie lange dauert der Quickstart?

Fünf Minuten für Registrierung + Key-Generierung + erster cURL. Die Generierung selbst dauert 1.5 bis 4 Minuten; plane also zehn Minuten Echtzeit ein, bevor du dein erstes Bild am Model siehst.

Brauche ich eine Kreditkarte zum Testen?

Neue Konten enthalten Test-credits, die du vor einer Zahlung nutzen kannst. Wenn du produktiv gehst, buche einen Plan für ein höheres monatliches Guthaben an credits und schnellere Rate Limits.

Welchen Endpoint sollte ich zuerst testen?

Apparel-Try-On (/api/v1/tryon/apparel) — er wird am häufigsten genutzt, die Dokumentation ist am vollständigsten und er deckt das Async- + Polling-Muster ab, das jeder andere Photta-Endpoint wiederverwendet. Sobald das sitzt, funktionieren Jewelry und Ghost Mannequin genauso.

Kann ich das direkt aus dem Browser ausführen?

Nein. Dein API-Key muss serverseitig bleiben — wenn du ihn an den Browser auslieferst, leakt er an jeden Besucher. Leite Aufrufe über einen schlanken Proxy auf deinem eigenen Backend weiter (Next.js Route Handler, Express, Flask, Lambda) und lass den Browser stattdessen mit deinem Proxy kommunizieren.

Verwandte Seiten

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

Du bist fünf Minuten von deinem ersten Bild entfernt

API-Key anfordernAPI erkunden
  • Bearer-Key
  • asynchron, Polling
  • 600 Anfragen/Min.