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

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

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

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"
}

Request-parameters

workflow_id

Type: stringVereist

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

images

Type: 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.

options

Type: 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

Type: 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

Type: integer

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

= 1

aspect_ratio

Type: 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:9
resolution

Type: string

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

= 2K

Waarden: 2K4K

Errors

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.

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.

  1. Stap 1

    Genereer een API-sleutel

    Workflows gebruiken dezelfde inloggegevens en hetzelfde creditsaldo als elke andere Photta-functionaliteit.

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

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

  4. 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.

  5. 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.

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

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