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
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')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "completed",
"output_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508-thumb.jpg",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z",
"completed_at": "2026-08-03T10:20:41Z",
"error_code": null,
"error_message": null
},
"request_id": "req_wfl003"
}Request-Parameter
workflow_idTyp: stringErforderlich
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
imagesTyp: 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.
optionsTyp: 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_textTyp: 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_imagesTyp: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratioTyp: 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:9resolutionTyp: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Werte:2K4K
Fehler
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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.
Schritt 1
API-Key generieren
Workflows nutzen dieselben Credentials und dasselbe Credit-Guthaben wie jede andere Photta-Capability.
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.
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.
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.
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.
Derselbe Endpoint in Node.js, Python und cURL
Node.js
Workflows API in Node.js
Rufen Sie Phottas workflows API von einem Node.js-Backend mit nativem fetch auf. Kein SDK erforderlich: Key speichern, Job absenden, Ergebnis pollen.
LesenPython
Workflows API in Python
Rufen Sie Phottas workflows API in Python mit der requests-Bibliothek auf. Dreißigzeiliger Wrapper, async-kompatibel über httpx, funktioniert in Django, FastAPI und Celery.
LesencURL
Workflows API mit cURL
Rufen Sie Phottas workflows API direkt über die Shell mit cURL auf. Übermitteln, pollen, herunterladen — jedes Snippet lässt sich für skriptbasierte Pipelines mit jq kombinieren.
Lesen
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
Funktionen
Virtuelle Try-on-API für Apparel
REST-API zur Platzierung von Bekleidung auf KI-Mannequins. Asynchron, 1.5–4 Minuten Generierungsdauer, 5 credits bei 2K, 6 bei 4K. Beispiele für cURL, Node.js und Python.
Zum EndpointFunktionen
Jewelry-Try-on-API für Halsketten, Ringe, Armbänder und Ohrringe
Halsketten, Ringe, Armbänder und Ohrringe via REST auf KI-Modellen platzieren. 5 credits bei 2K, integrierte Nahaufnahme-Mannequins, reflexionsbewusstes Rendering aus der Photta-Dokumentation.
Zum EndpointBuild
Einen Service für KI-Produktfotografie aufbauen
Das Gründer-Playbook für den Weiterverkauf der Virtual-Try-on-API von Photta als White-Label-SaaS: Mandanten-Keys, Batch-Fanout, Abrechnung nach Credits, SLA-Realität.
Zum EndpointVergleich
Photta vs. Ayna — Entwickler-API oder Shopify-first-Studio
Photta vs. Ayna im Vergleich: drei REST-Endpoints vs. ein Shopify-fokussiertes Studio + API. Beide haben Stärken. Daten von den jeweiligen Websites vom 2026-04-19.
Zum EndpointSchnellstart
Erstes Photta-Bild in unter 5 Minuten.
Registrieren, API-Key generieren, ersten cURL-Aufruf ausführen, pollen bis zum Abschluss, Ergebnis persistieren. 5 Schritte, durchgängig dokumentiert.
Zum EndpointReferenz
Photta API-Fehler
Die vollständige Liste der Photta API-Fehlertypen samt Statuscodes, das Format des Error-Bodys und welche Fehler sich für einen Retry eignen.
Zum EndpointReferenz
Photta API Rate Limits
Das Photta API Rate Limit, sein Zeitfenster, der Retry-After-Header, das Polling-Intervall und die tarifbasierten Concurrency-Limits, alles direkt aus der API-Dokumentation.
Zum Endpoint
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