Capability · Workflows

Workflows API ein Aufruf, ein Preset

In aller Kürze

Die Workflows API von Photta führt fertige Szenen-Templates mit deinen Produktbildern aus. Katalog abrufen, Bild-Slots und Optionen des Workflows befüllen, POST ausführen, dann jedes zurückgegebene Element bis zum Abschluss pollen.

  • Typische Dauer: 20–60 sec / 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/workflows/{workflow_id}
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/workflows/jewelry-studio-shot \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "images": {
    "jewelry": [
      "https://cdn.yourstore.com/products/gold-ring.jpg"
    ]
  },
  "options": {
    "jewelryLighting": "dramatic",
    "backdrop": "dark"
  },
  "user_text": "hero shot, ring angled slightly toward the camera",
  "num_images": 2,
  "aspect_ratio": "3:4",
  "resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

Auf einen Blick

Auf einen Blick

Endpoint
POST /api/v1/workflows/{workflow_id}
Authentifizierung
Bearer-API-Schlüssel
Verarbeitung
Asynchron — Polling über den Status-Endpoint
Typische Dauer
20–60 sec / 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/workflows/jewelry-studio-shot \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "images": {
    "jewelry": [
      "https://cdn.yourstore.com/products/gold-ring.jpg"
    ]
  },
  "options": {
    "jewelryLighting": "dramatic",
    "backdrop": "dark"
  },
  "user_text": "hero shot, ring angled slightly toward the camera",
  "num_images": 2,
  "aspect_ratio": "3:4",
  "resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Abgeschlossen

{
  "data": {
    "items": [
      {
        "id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
        "workflow_id": "jewelry-studio-shot",
        "status": "processing",
        "resolution": "2K",
        "aspect_ratio": "3:4",
        "credits_used": 4,
        "created_at": "2026-08-03T10:20:00Z"
      },
      {
        "id": "wfl_8b2d64f0a1c9573ee4082d6cb95a3f17",
        "workflow_id": "jewelry-studio-shot",
        "status": "processing",
        "resolution": "2K",
        "aspect_ratio": "3:4",
        "credits_used": 4,
        "created_at": "2026-08-03T10:20:00Z"
      }
    ],
    "workflow_id": "jewelry-studio-shot",
    "workflow_version": 1,
    "credits_used": 8
  },
  "request_id": "req_wfl002"
}

Request-Parameter

workflow_id

Typ: stringErforderlich

The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.

images

Typ: objectErforderlich

Map of image slot id → array of images (https URL or base64 data URI). Slot ids, required flags, and min/max image counts come from the workflow's image_slots in the catalog. Missing entirely, missing a required slot, using an unknown slot, or exceeding a slot's max_images returns 400.

options

Typ: object

Map of option id → choice id, both from the workflow's options in the catalog. Omitted options use their default_choice. Unknown option ids or choice ids return 400, as does sending an option that a filled image slot replaces (see replaces_options).

user_text

Typ: string

Free-text styling/framing request (e.g. "hero shot, slightly angled"). Max 500 characters — excess is silently truncated. It never overrides product fidelity: the product always stays true to your images.

num_images

Typ: integer

Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.

= 1

aspect_ratio

Typ: string

Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).

= 3:4

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

Typ: string

Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.

= 2K

Werte: 2K4K

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.

Katalog abrufen, Slots befüllen, ausführen

Workflows auflisten, deklarierte Slots befüllen, absenden, jedes Element pollen, herunterladen.

  1. Schritt 1

    API-Key generieren

    Workflows nutzen dieselben Credentials und dasselbe Credit-Guthaben wie jede andere Photta-Capability.

  2. Schritt 2

    Workflow-Katalog auflisten

    GET `/api/v1/workflows` gibt die 53 Templates aus 7 Kategorien zurück. Jedes deklariert seine eigenen Bild-Slots, Options-Enums und das Standard-Seitenverhältnis. Filtere mit `category` — eine unbekannte Kategorie liefert 400 zurück, statt ignoriert zu werden.

  3. Schritt 3

    Den Run per POST starten

    POST `/api/v1/workflows/:workflow_id` mit `images` (Slot-ID zu Bildern) und `options` (Option-ID zu Choice-ID), beide aus dem Katalogeintrag entnommen. `user_text` akzeptiert Styling-Wünsche als Freitext und `num_images` führt 1 bis 4 Bilder in einem Aufruf aus.

  4. Schritt 4

    Jedes Element pollen

    Die 202-Response enthält ein Element pro angefordertem Bild. GET `/api/v1/workflows/generations/:id` alle 3 Sekunden für jede ID aufrufen, bis `data.status` auf `completed` oder `failed` steht; typische Fertigstellung dauert 20 bis 60 Sekunden pro Bild.

  5. Schritt 5

    Herunterladen und persistieren

    Jedes abgeschlossene Element enthält seine eigene `output_url`. Elemente werden unabhängig voneinander fertiggestellt, sodass du das erste veröffentlichen kannst, während der Rest noch rendert.

Fragen, die Entwickler vor dem Ausführen von Workflows stellen

Was ist die Workflows API?

Ein Katalog fertiger Szenen-Templates, die du mit deinen eigenen Produktfotos ausführst. Statt einen Prompt zusammenzubauen, wählst du einen Workflow und befüllst die darin deklarierten Bild-Slots und Optionen.

Wie viel kostet ein Workflow-Run?

4 credits pro Bild bei 2K und 5 pro Bild bei 4K, multipliziert mit `num_images`. Der Katalog enthält den Live-Preis für jeden Workflow — lies ihn direkt von dort aus, statt Annahmen zu treffen.

Wie finde ich eine Workflow-ID?

GET `/api/v1/workflows`. Jeder Eintrag enthält seine ID, seine Kategorie, seine Bild-Slots und seine Optionen. Filtere die Liste mit `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` oder `watch`.

Was gehört in images und options?

`images` mappt eine Slot-ID aus dem Katalogeintrag auf ein Array von Bildern, als https-URLs oder Base64-Data-URIs. `options` mappt eine Option-ID auf eine der Choice-IDs dieser Option. Beide Strukturen stammen aus dem Katalog – genau deshalb funktioniert die Integration auch bei neuen Workflows ohne Anpassung.

Wie viele Bilder kann ein einzelner Run erzeugen?

`num_images` akzeptiert 1 bis 4. Jedes Bild wird unabhängig generiert und erhält eine eigene Item-ID in der Response, sodass ein Fehler bei einem Bild die anderen nicht beeinträchtigt.

Wie führe ich das Polling für die Ergebnisse durch?

Polle jedes Element separat: GET `/api/v1/workflows/generations/:id` alle 3 Sekunden. GET `/api/v1/workflows/generations/list` liefert eine paginierte Ansicht, gefiltert nach `workflow_id` oder `status`.

Verwandte Capabilities

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.

  • 20–60 sec / image
  • 4 Credits bei 2K · 5 Credits bei 4K
  • asynchron, Polling
  • 600 Anfragen/Min.
  • Bearer-Key