Funksjonalitet · Workflows

Workflows API ett kall, én forhåndsinnstilling

I én setning

Phottas workflows-API kjører ferdige scenemaler mot produktbildene dine. Hent katalogen, fyll inn arbeidsflytens bildespor og alternativer, POST, og poll deretter hvert returnerte element til det er fullført.

  • Typisk tidsbruk: 20–60 sec / image
  • Credits: 4 credits ved 2K · 5 credits ved 4K
  • Prosessering: asynkron, polling
  • Grenser: 600 forespørsler/min
  • Autentisering: Bearer-nøkkel

Hvert tall på denne siden er hentet fra dokumentasjonen for Photta-API-et · verifisert

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 oppsummert

Kort oppsummert

Endepunkt
POST /api/v1/workflows/{workflow_id}
Autentisering
Bearer API-nøkkel
Prosessering
Asynkron – poll status-endepunktet
Typisk tidsbruk
20–60 sec / image
Credits
4 credits ved 2K · 5 credits ved 4K
Bildeformater
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Inndatagrenser
Opptil 10 MB per bilde; JPEG, PNG, WebP
Idempotent
Nei

Forespørsel og respons

Forespørsel

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

Forespørselsparametere

workflow_id

Type: stringPåkrevd

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

images

Type: objectPåkrevd

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

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

Verdier: 2K4K

Feil

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.

Grenser

  • 600 forespørsler per minutt per API-nøkkel (Fast tidsvindu; grensen er lik for alle abonnementer)
  • En 429 inneholder Retry-After: 30 sekunder
  • Opptil 10 MB per bilde
  • Formater: JPEG, PNG, WebP
  • Samtidige batcher per abonnement: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Kun polling – API-et sender ikke webhooks.

Hent katalogen, fyll sporene, kjør

List ut arbeidsflytene, fyll deres deklarerte spor, send inn, poll hvert element, last ned.

  1. Trinn 1

    Generer en API-nøkkel

    Arbeidsflyter bruker samme autentisering og samme saldo med credits som alle andre Photta-funksjoner.

  2. Trinn 2

    List ut arbeidsflytkatalogen

    GET `/api/v1/workflows` returnerer de 53 malene fordelt på 7 kategorier, der hver deklarerer sine egne bildespor, alternativenums og standard størrelsesforhold. Filtrer med `category` — en ukjent kategori returnerer 400 i stedet for å bli ignorert.

  3. Trinn 3

    POST kjøringen

    POST `/api/v1/workflows/:workflow_id` med `images` (spor-id til bilder) og `options` (alternativ-id til valg-id), begge hentet fra katalogoppføringen. `user_text` godtar en fritekstforespørsel om styling, og `num_images` kjører 1 til 4 bilder i ett kall.

  4. Trinn 4

    Poll hvert element

    202-responsen inneholder ett element per forespurte bilde. GET `/api/v1/workflows/generations/:id` hvert 3. sekund for hver id til `data.status` er `completed` eller `failed`; typisk fullføringstid er 20 til 60 sekunder per bilde.

  5. Trinn 5

    Last ned og lagre

    Hvert fullførte element har sin egen `output_url`. Elementer fullføres uavhengig av hverandre, slik at du kan publisere det første mens resten fortsatt gjengis.

Spørsmål utviklere stiller før de kjører arbeidsflyter

Hva er workflows-API-et?

En katalog med ferdige scenemaler du kjører mot dine egne produktfotografier. I stedet for å sette sammen en prompt, velger du en arbeidsflyt og fyller ut bildesporene og alternativene den deklarerer.

Hvor mye koster en arbeidsflytkjøring?

4 credits per bilde i 2K og 5 per bilde i 4K, multiplisert med `num_images`. Katalogen inneholder den gjeldende prisen for hver arbeidsflyt — les den derfra i stedet for å anta.

Hvordan finner jeg en arbeidsflyt-id?

GET `/api/v1/workflows`. Hver oppføring inneholder sin id, sin kategori, sine bildespor og sine alternativer. Filtrer listen med `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` eller `watch`.

Hva skal sendes i images og options?

`images` tilordner en spor-id fra katalogoppføringen til en matrise med bilder, som https-URL-er eller base64 data-URI-er. `options` tilordner en alternativ-id til en av det alternativets valg-id-er. Begge strukturer kommer fra katalogen, og det er grunnen til at integrasjonen tåler nye arbeidsflyter.

Hvor mange bilder kan én kjøring produsere?

`num_images` godtar 1 til 4. Hvert bilde genereres uavhengig og får sin egen element-id i responsen, slik at ett kan feile uten at de andre påvirkes.

Hvordan poller jeg etter resultatene?

Poll hvert element separat: GET `/api/v1/workflows/generations/:id` hvert 3. sekund. GET `/api/v1/workflows/generations/list` gir en paginert visning filtrert etter `workflow_id` eller `status`.

Relaterte funksjoner

Hvert tall på denne siden er hentet fra dokumentasjonen for Photta-API-et · verifisert

Prøv API-et på fem minutter

Generer en Photta API-nøkkel, lim inn cURL-kodesnutten ovenfor, og du har ditt første bilde på modell før kaffen er ferdig traktet.

  • 20–60 sec / image
  • 4 credits ved 2K · 5 credits ved 4K
  • asynkron, polling
  • 600 forespørsler/min
  • Bearer-nøkkel