Capability · Workflows
Workflows API één call, één preset
In één zin
Photta’s workflows API voert kant-en-klare scènetemplates uit op je productafbeeldingen. Haal de catalogus op, vul de afbeeldingslots en opties van de workflow in, doe een POST en poll vervolgens elk geretourneerd item totdat het voltooid is.
- Typische duur: 20–60 sec / image
- Credits: 4 credits bij 2K · 5 credits bij 4K
- Verwerking: async, polling
- Limieten: 600 requests/min
- Authenticatie: Bearer key
Elk getal op deze pagina is afkomstig uit de Photta-API-documentatie · gecontroleerd
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"]In één oogopslag
In één oogopslag
- Endpoint
- POST /api/v1/workflows/{workflow_id}
- Authenticatie
- Bearer API key
- Verwerking
- Asynchroon — poll het status-endpoint
- Typische duur
- 20–60 sec / image
- Credits
- 4 credits bij 2K · 5 credits bij 4K
- Beeldverhoudingen
- 3:4 · 1:1 · 4:3 · 9:16 · 16:9
- Invoerlimieten
- Tot 10 MB per afbeelding; JPEG, PNG, WebP
- Idempotent
- Nee
Request en 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 / Completed
{
"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-parameters
workflow_idType: stringVereist
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
imagesType: objectVereist
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.
optionsType: 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_textType: 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_imagesType: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratioType: string
Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).
= 3:4
Waarden:3:41:14:39:1616:9resolutionType: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Waarden:2K4K
Errors
- 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.
Limieten
- 600 verzoeken per minuut per API key (Vast venster; de limiet is identiek op elk abonnement)
- Een 429 bevat Retry-After: 30 seconden
- Tot 10 MB per afbeelding
- Formaten: JPEG, PNG, WebP
- Gelijktijdige batches per abonnement: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
- Uitsluitend polling — de API stuurt geen webhooks.
Haal de catalogus op, vul de slots in, voer uit
Lijst de workflows op, vul hun gedeclareerde slots in, verzend, poll elk item, download.
Stap 1
Genereer een API-sleutel
Workflows gebruiken dezelfde inloggegevens en hetzelfde creditsaldo als elke andere Photta-functionaliteit.
Stap 2
Vraag de workflowcatalogus op
GET `/api/v1/workflows` retourneert de 53 templates verdeeld over 7 categorieën, die elk hun eigen afbeeldingslots, optie-enums en standaard aspect ratio declareren. Filter met `category` — een onbekende categorie retourneert 400 in plaats van te worden genegeerd.
Stap 3
POST de run
POST `/api/v1/workflows/:workflow_id` met `images` (slot id naar afbeeldingen) en `options` (optie id naar keuze id), beide overgenomen uit het catalogusitem. `user_text` accepteert een stylingverzoek in vrije tekst en `num_images` voert 1 tot 4 afbeeldingen uit in één call.
Stap 4
Poll elk item
De 202-respons bevat één item per aangevraagde afbeelding. GET `/api/v1/workflows/generations/:id` elke 3 seconden voor elk id totdat `data.status` `completed` of `failed` is; een typische voltooiing duurt 20 tot 60 seconden per afbeelding.
Stap 5
Download en sla op
Elk voltooid item bevat zijn eigen `output_url`. Items worden onafhankelijk van elkaar voltooid, zodat je het eerste al kunt publiceren terwijl de rest nog rendert.
Hetzelfde endpoint in Node.js, Python en cURL
Node.js
Workflows API in Node.js
Roep Photta's workflows API aan vanuit een Node.js-backend met native fetch. Geen SDK vereist: sla je sleutel op, verzend de taak, poll voor het resultaat.
LezenPython
Workflows API in Python
Roep Photta's workflows API aan in Python met de requests-bibliotheek. Een wrapper van dertig regels, async-vriendelijk via httpx, werkt in Django, FastAPI en Celery.
LezencURL
Workflows API met cURL
Roep Photta's workflows API direct aan vanuit de shell met cURL. Verzenden, pollen, downloaden — elk fragment werkt naadloos samen met jq voor gescripte pipelines.
Lezen
Vragen die ontwikkelaars stellen voordat ze workflows uitvoeren
Wat is de workflows API?
Een catalogus van kant-en-klare scènetemplates die je uitvoert op je eigen productfoto's. In plaats van een prompt samen te stellen, kies je een workflow en vul je de afbeeldingslots en opties in die deze declareert.
Hoeveel kost een workflow-run?
4 credits per afbeelding op 2K en 5 per afbeelding op 4K, vermenigvuldigd met `num_images`. De catalogus bevat de actuele prijs voor elke workflow — lees deze daaruit af in plaats van aannames te doen.
Hoe vind ik een workflow id?
GET `/api/v1/workflows`. Elk item bevat zijn id, categorie, afbeeldingslots en opties. Filter de lijst met `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` of `watch`.
Wat hoort er in images en options?
`images` koppelt een slot id uit het catalogusitem aan een array van afbeeldingen, als https-URL's of base64 data-URI's. `options` koppelt een optie id aan een van de keuze-id's van die optie. Beide structuren komen uit de catalogus, waardoor de integratie compatibel blijft met nieuwe workflows.
Hoeveel afbeeldingen kan één run produceren?
`num_images` accepteert 1 tot 4. Elke afbeelding wordt onafhankelijk gegenereerd en krijgt een eigen item id in de respons, zodat er één kan mislukken zonder de rest te beïnvloeden.
Hoe poll ik voor de resultaten?
Poll elk item afzonderlijk: GET `/api/v1/workflows/generations/:id` elke 3 seconden. GET `/api/v1/workflows/generations/list` biedt een gepagineerd overzicht gefilterd op `workflow_id` of `status`.
Gerelateerde functionaliteiten
Mogelijkheden
Virtual try-on API voor kleding
REST API die kleding op AI-mannequins plaatst. Asynchroon, generatie in 1.5–4 minuten, 5 credits bij 2K, 6 bij 4K. Voorbeelden in cURL, Node.js en Python.
Bekijk het endpointMogelijkheden
Sieraden try-on API voor kettingen, ringen, armbanden en oorbellen
Plaats kettingen, ringen, armbanden en oorbellen op AI-modellen via REST. 5 credits bij 2K, ingebouwde close-up mannequins, reflectie-bewuste rendering uit de Photta-documentatie.
Bekijk het endpointBouwen
Bouw een AI-dienst voor productfotografie
Een playbook voor founders om de virtuele try-on API van Photta door te verkopen als een white-label SaaS: tenant-sleutels, batch-distributie, facturatie per credit en de realiteit rond SLA's.
Bekijk het endpointVergelijken
Photta vs Ayna — developer-API of Shopify-first studio
Photta vs Ayna vergeleken: drie REST endpoints vs een Shopify-first studio + API. Beide hebben sterke punten. Afkomstig van elke site op 2026-04-19.
Bekijk het endpointSnelstartgids
Eerste Photta-afbeelding in minder dan vijf minuten.
Registreer je, genereer een API-sleutel, voer je eerste cURL-call uit, poll totdat deze is voltooid, sla het resultaat op. Vijf stappen, end-to-end gedocumenteerd.
Bekijk het endpointReferentie
Photta API-fouten
De volledige lijst van Photta API-fouttypen met hun statuscodes, de structuur van een foutbody, en welke fouten het waard zijn om opnieuw te proberen.
Bekijk het endpointReferentie
Photta API rate limits
De Photta API rate limit, het bijbehorende venster, de Retry-After-header, het polling-interval en de gelijktijdigheidslimieten per abonnement, rechtstreeks uit de API-documentatie.
Bekijk het endpoint
Elk getal op deze pagina is afkomstig uit de Photta-API-documentatie · gecontroleerd
Probeer de API in vijf minuten
Genereer een Photta API-sleutel, plak het bovenstaande cURL-fragment en je hebt je eerste afbeelding op een model voordat de koffie klaar is.
- 20–60 sec / image
- 4 credits bij 2K · 5 credits bij 4K
- async, polling
- 600 requests/min
- Bearer key