Kapabilitet · Workflows

Workflows API ét kald, ét preset

I én sætning

Phottas workflows API kører færdige sceneskabeloner mod dine produktbilleder. Hent kataloget, udfyld workflowets billedslots og indstillinger, send en POST, og poll hvert returneret element, indtil det er færdigt.

  • Typisk tid: 20–60 sec / image
  • Credits: 4 credits ved 2K · 5 credits ved 4K
  • Behandling: async, polling
  • Grænser: 600 requests/min
  • Autentifikation: Bearer key

Hvert tal på denne side stammer fra Photta API-dokumentationen · tjekket

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

Kort fortalt

Kort fortalt

Endpoint
POST /api/v1/workflows/{workflow_id}
Autentifikation
Bearer API-nøgle
Behandling
Asynkron — poll status-endpointet
Typisk tid
20–60 sec / image
Credits
4 credits ved 2K · 5 credits ved 4K
Billedformater
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Inputgrænser
Op til 10 MB pr. billede; JPEG, PNG, WebP
Idempotent
Nej

Request og 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-parametre

workflow_id

Type: stringPåkrævet

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

images

Type: objectPåkrævet

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

Værdier: 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

Værdier: 2K4K

Fejl

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 anmodninger i minuttet pr. API-nøgle (Fast vindue; grænsen er den samme på alle planer)
  • En 429 indeholder Retry-After: 30 sekunder
  • Op til 10 MB pr. billede
  • Formater: JPEG, PNG, WebP
  • Samtidige batches pr. plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Kun polling — API'et sender ingen webhooks.

Hent kataloget, udfyld slots, kør

Oplist workflows, udfyld deres deklarerede slots, indsend, poll hvert element, download.

  1. Trin 1

    Generér en API-nøgle

    Workflows bruger de samme legitimationsoplysninger og den samme credits-saldo som alle andre Photta-kapabiliteter.

  2. Trin 2

    Oplist workflowkataloget

    GET `/api/v1/workflows` returnerer de 53 skabeloner fordelt på 7 kategorier, hvor hver især deklarerer sine egne billedslots, valgmuligheds-enums og standardformatforhold. Filtrér med `category` — en ukendt kategori returnerer 400 frem for at blive ignoreret.

  3. Trin 3

    POST kørslen

    POST `/api/v1/workflows/:workflow_id` med `images` (slot-id til billeder) og `options` (option-id til choice-id), begge hentet fra katalogposten. `user_text` accepterer en styling-forespørgsel i fritekst, og `num_images` kører 1 til 4 billeder i ét kald.

  4. Trin 4

    Poll hvert element

    202-svaret indeholder ét element pr. anmodet billede. GET `/api/v1/workflows/generations/:id` hvert 3. sekund for hvert id, indtil `data.status` er `completed` eller `failed`; typisk færdiggørelsestid er 20 til 60 sekunder pr. billede.

  5. Trin 5

    Download og gem permanent

    Hvert fuldført element har sin egen `output_url`. Elementer bliver færdige uafhængigt af hinanden, så du kan udgive det første, mens resten stadig renderes.

Spørgsmål udviklere stiller, før de kører workflows

Hvad er workflows API'et?

Et katalog af færdige sceneskabeloner, du kører mod dine egne produktfotografier. I stedet for at sammensætte en prompt vælger du et workflow og udfylder de billedslots og indstillinger, det deklarerer.

Hvor meget koster en workflow-kørsel?

4 credits pr. billede i 2K og 5 pr. billede i 4K, ganget med `num_images`. Kataloget indeholder live-prisen for hvert workflow — læs den derfra i stedet for at antage den.

Hvordan finder jeg et workflow-id?

GET `/api/v1/workflows`. Hver post indeholder sit id, sin kategori, sine billedslots og sine indstillinger. Filtrér listen med `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` eller `watch`.

Hvad skal der sendes i images og options?

`images` mapper et slot-id fra katalogposten til et array af billeder som https-URL'er eller base64-data-URI'er. `options` mapper et option-id til et af denne indstillings choice-id'er. Begge datastrukturer stammer fra kataloget, hvilket sikrer, at integrationen også fungerer med nye workflows.

Hvor mange billeder kan én kørsel generere?

`num_images` accepterer 1 til 4. Hvert billede genereres uafhængigt og får sit eget element-id i svaret, så ét kan fejle, uden at de andre påvirkes.

Hvordan poller jeg for resultaterne?

Poll hvert element separat: GET `/api/v1/workflows/generations/:id` hvert 3. sekund. GET `/api/v1/workflows/generations/list` giver en sideopdelt visning filtreret efter `workflow_id` eller `status`.

Relaterede kapabiliteter

Hvert tal på denne side stammer fra Photta API-dokumentationen · tjekket

Prøv API'et på fem minutter

Generér en Photta API-nøgle, indsæt cURL-kodestykket ovenfor, og du har dit første billede på en model, før kaffen er færdigbrygget.

  • 20–60 sec / image
  • 4 credits ved 2K · 5 credits ved 4K
  • async, polling
  • 600 requests/min
  • Bearer key