Funktion · Batch-Ghost-Mannequin

Batch-Ghost-Mannequin-API für komplette Kataloge

In aller Kürze

Phottas Batch-Ghost-Mannequin-Endpoint akzeptiert ein Array von Kleidungsfotos und liefert eine Batch-ID sowie eine Element-ID pro Bild zurück. Credits für den gesamten Batch werden vorab reserviert; polle den Batch für einen aggregierten Status.

  • Typische Dauer: 1.5–4 min per image
  • 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/batch
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin/batch \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_images": [
    {
      "image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/shirt-front.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/trousers-front.jpg",
      "image_side": "front"
    }
  ],
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, buttoned up",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
A garment shown without its mannequin by the ghost mannequin API
Beispielausgabe

Auf einen Blick

Auf einen Blick

Endpoint
POST /api/v1/ghost-mannequin/batch
Authentifizierung
Bearer-API-Schlüssel
Verarbeitung
Asynchron — Polling über den Status-Endpoint
Typische Dauer
1.5–4 min per image
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

Request und Response

Request

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

202 Accepted / Abgeschlossen

{
  "data": {
    "batch_id": "gmb_x7y8z9",
    "status": "processing",
    "total": 3,
    "completed": 0,
    "failed": 0,
    "items": [
      {
        "id": "gm_p1q2r3",
        "status": "processing"
      },
      {
        "id": "gm_s4t5u6",
        "status": "processing"
      },
      {
        "id": "gm_v7w8x9",
        "status": "processing"
      }
    ],
    "style": "3d",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_reserved": 12,
    "created_at": "2026-04-10T16:05:00Z"
  },
  "request_id": "req_gmb001"
}

Request-Parameter

product_images

Typ: array[object]Erforderlich

Array of image objects. Each object contains "image" (URL or base64), optional "back_image", and optional "image_side". API batch caps (5× the dashboard limit): Free/Hobby/Hobby v2 5, Seller/Starter 10, Brand/Pro 25, Studio/Premium 50.

angle

Typ: string

Applied to all images. "side" reconstructs the side view from each front photo (plus back_image when provided) — see the single-generate endpoint for details.

= straight

Werte: straightbackside
style

Typ: string

Applied to all images.

= 3d

Werte: 3dflat_lay
background_color

Typ: string

Applied to all images.

= white

Werte: whitegraybeigeblack
resolution

Typ: string

Applied to all images. "2K" = 4 credits each. "4K" = 5 credits each. 4K is produced natively in a single generation per item — pick it upfront; the resolution cannot be changed after creation. Note: 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

Werte: 2K4K
aspect_ratio

Typ: string

Applied to all images. Note: 1:1 is not available at 4K resolution — 1:1 combined with 4K returns 400.

= 3:4

Werte: 3:41:14:39:1616:9
user_instruction

Typ: string

Batch-level: one note applied to every item. Optional free-form string, max 400 characters (anything longer is silently truncated). A guarded steer for ambiguous rendering choices — e.g. "closed front", "cream interior lining", "buttoned up" — it never overrides the source garment, brand label, or structural reconstruction, and it is explicitly NOT a determinism/seed control.

brand_label_id

Typ: string

Applied to all images. Brand label UUID returned by the Brand Labels API. API v1 request fields use snake_case; use brand_label_id.

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.

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.

Ein Request, eine ganze Reihe von Kleidungsstücken

Array zusammenstellen, einmal absenden, den Batch pollen, jedes Element herunterladen.

  1. Schritt 1

    API-Schlüssel generieren

    Batch-Ghost-Mannequin nutzt dieselben Zugangsdaten und dasselbe Credit-Guthaben wie jede andere Photta-Funktion.

  2. Schritt 2

    Bild-Array zusammenstellen

    `product_images` akzeptiert ein Objekt pro Kleidungsstück: `image`, plus optional `back_image` und `image_side`. Das API-Batch-Limit liegt bei 5 Bildern für Free und Hobby, 10 für Seller, 25 für Brand und 50 für Studio.

  3. Schritt 3

    Den Batch per POST senden

    POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution` und `aspect_ratio` gelten für jedes Element, und `user_instruction` fügt allen eine Notiz von bis zu 400 Zeichen hinzu. Credits für den gesamten Batch werden reserviert, bevor das erste Element gerendert wird.

  4. Schritt 4

    Den Batch pollen

    GET `/api/v1/ghost-mannequin/batch/:id` alle 3 Sekunden. Der Body enthält `total`, `completed`, `failed` und eine Aufschlüsselung pro Element, sodass du mit dem Download beginnen kannst, bevor das letzte Kleidungsstück fertig ist.

  5. Schritt 5

    Jedes Ergebnis herunterladen

    Jedes fertiggestellte Element enthält eine eigene `output_url`, `credits_used` und die Dauer. Bei fehlgeschlagenen Elementen werden die reservierten Credits erstattet und in `credits_refunded` ausgewiesen.

Fragen von Entwicklern vor dem Ausführen von Batches

Welchen Mehrwert bietet der Batch-Endpoint?

Er nimmt ein Array von Kleidungsfotos in einem einzigen Request entgegen und verarbeitet sie im Hintergrund. Du erhältst eine Batch-ID für die aggregierte Ansicht und eine Element-ID pro Foto, statt Dutzende separater Jobs verwalten zu müssen.

Wie viele Bilder passen in einen Batch?

Das API-Batch-Limit liegt bei 5 Bildern für Free und Hobby, 10 für Seller, 25 für Brand und 50 für Studio – das Fünffache des Dashboard-Limits. Ein Batch, der größer ist als dein Tarif erlaubt, liefert 400 zurück.

Wie werden Credits für einen Batch abgerechnet?

Der gesamte Batch wird vorab reserviert: Bilder multipliziert mit dem Preis pro Bild, 4 Credits bei 2K oder 5 bei 4K. Reicht das Guthaben nicht für die Reservierung aus, gibt der Request 402 zurück und nichts wird gerendert.

Was passiert, wenn ein einzelnes Element fehlschlägt?

Der Rest des Batches läuft weiter. Der Batch-Body gibt `failed` neben `completed` an, und die reservierten Credits für fehlgeschlagene Elemente werden über `credits_refunded` zurückerstattet.

Wie viele Batches können gleichzeitig laufen?

Gleichzeitige aktive Batches sind je nach Tarif begrenzt: Free 1, Hobby 2, Seller 3, Brand 4 und Studio 6. Das Überschreiten des Limits gibt 409 zurück – polle den aktiven Batch, bis er abgeschlossen ist, und sende ihn dann erneut.

Wie polle ich einen Batch?

GET `/api/v1/ghost-mannequin/batch/:id` alle 3 Sekunden für den aggregierten Status, oder polle ein einzelnes Element über den regulären Ghost-Mannequin-Statuspfad, wenn du Details zu einem bestimmten Kleidungsstück benötigst.

Verwandte Funktionen

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

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 per image
  • 4 Credits bei 2K · 5 Credits bei 4K
  • asynchron, Polling
  • 600 Anfragen/Min.
  • Bearer-Key