Funktion · Workflows

Workflows API ett anrop, en förinställning

I en mening

Phottas workflows API kör färdiga scenmallar mot dina produktbilder. Hämta katalogen, fyll i arbetsflödets bildplatser och alternativ, gör POST och polla sedan varje returnerat objekt tills det slutförs.

  • Typisk tid: 20–60 sec / image
  • Credits: 4 credits vid 2K · 5 credits vid 4K
  • Bearbetning: asynkron, polling
  • Gränser: 600 requests/min
  • Autentisering: Bearer-nyckel

Varje siffra på den här sidan kommer från Photter API-dokumentationen · kontrollerad

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

I korthet

I korthet

Endpoint
POST /api/v1/workflows/{workflow_id}
Autentisering
Bearer API-nyckel
Bearbetning
Asynkron — polla status-endpointen
Typisk tid
20–60 sec / image
Credits
4 credits vid 2K · 5 credits vid 4K
Bildförhållanden
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Indatagränser
Upp till 10 MB per bild; JPEG, PNG, WebP
Idempotent
Nej

Request och 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-parametrar

workflow_id

Typ: stringObligatorisk

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

images

Typ: objectObligatorisk

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

Värden: 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

Värden: 2K4K

Fel

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.

Gränser

  • 600 anrop per minut per API-nyckel (Fast fönster; gränsen är densamma på alla planer)
  • En 429 innehåller Retry-After: 30 sekunder
  • Upp till 10 MB per bild
  • Format: JPEG, PNG, WebP
  • Samtidiga batcher per plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Endast polling — API:et skickar inga webhooks.

Hämta katalogen, fyll i platserna, kör

Lista arbetsflödena, fyll i deras deklarerade platser, skicka in, polla varje objekt, ladda ner.

  1. Steg 1

    Generera en API-nyckel

    Workflows använder samma inloggningsuppgifter och samma credits-saldo som alla andra Photta-funktioner.

  2. Steg 2

    Lista workflow-katalogen

    GET `/api/v1/workflows` returnerar 53 mallar fördelade på 7 kategorier, där varje mall deklarerar sina egna bildplatser, alternativ-enums och standardproportioner. Filtrera med `category` — en okänd kategori returnerar 400 istället för att ignoreras.

  3. Steg 3

    POST för körningen

    Gör POST mot `/api/v1/workflows/:workflow_id` med `images` (plats-id till bilder) och `options` (alternativ-id till val-id), båda hämtade från katalogposten. `user_text` accepterar ett stilönskemål i fritext, och `num_images` kör 1 till 4 bilder i ett anrop.

  4. Steg 4

    Polla varje objekt

    202-svaret innehåller ett objekt per begärd bild. Gör GET mot `/api/v1/workflows/generations/:id` var 3:e sekund för varje id tills `data.status` är `completed` eller `failed`; normal slutförandetid är 20 till 60 sekunder per bild.

  5. Steg 5

    Ladda ner och spara

    Varje slutfört objekt har sin egen `output_url`. Objekten blir klara oberoende av varandra, så du kan publicera det första medan resten fortfarande renderas.

Frågor utvecklare ställer innan de kör workflows

Vad är workflows API?

En katalog med färdiga scenmallar som du kör mot dina egna produktfotografier. Istället för att sätta ihop en prompt väljer du ett arbetsflöde och fyller i de bildplatser och alternativ som det deklarerar.

Hur mycket kostar en workflow-körning?

4 credits per bild i 2K och 5 per bild i 4K, multiplicerat med `num_images`. Katalogen innehåller det aktuella priset för varje arbetsflöde — läs av det därifrån istället för att gissa.

Hur hittar jag ett workflow-id?

GET `/api/v1/workflows`. Varje post innehåller sitt id, sin kategori, sina bildplatser och sina alternativ. Filtrera listan med `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` eller `watch`.

Vad skickas i images och options?

`images` mappar ett plats-id från katalogposten till en array av bilder, som https-URL:er eller base64 data-URI:er. `options` mappar ett alternativ-id till ett av det alternativets val-id:n. Båda strukturerna kommer från katalogen, vilket gör att integrationen fortsätter fungera även när nya arbetsflöden tillkommer.

Hur många bilder kan en körning producera?

`num_images` accepterar 1 till 4. Varje bild genereras oberoende och får sitt eget objekt-id i svaret, så en bild kan misslyckas utan att de andra påverkas.

Hur pollar jag efter resultaten?

Polla varje objekt separat: GET `/api/v1/workflows/generations/:id` var 3:e sekund. GET `/api/v1/workflows/generations/list` ger en paginerad vy filtrerad på `workflow_id` eller `status`.

Relaterade funktioner

Varje siffra på den här sidan kommer från Photter API-dokumentationen · kontrollerad

Testa API:et på fem minuter

Generera en Photta API-nyckel, klistra in cURL-kodfragmentet ovan, och du har din första bild på en modell innan kaffet har bryggts klart.

  • 20–60 sec / image
  • 4 credits vid 2K · 5 credits vid 4K
  • asynkron, polling
  • 600 requests/min
  • Bearer-nyckel