Możliwość · Workflows

Workflows API jedno wywołanie, jeden preset

W jednym zdaniu

API workflows od Photta uruchamia gotowe szablony scen na Twoich zdjęciach produktów. Pobierz katalog, wypełnij sloty na zdjęcia i opcje danego workflow, wyślij POST, a następnie odpytuj o każdy zwrócony element, aż zakończy przetwarzanie.

  • Typowy czas: 20–60 sec / image
  • Credits: 4 credits w 2K · 5 credits w 4K
  • Przetwarzanie: asynchroniczne, polling
  • Limity: 600 requests/min
  • Uwierzytelnianie: Klucz Bearer

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono

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

W skrócie

W skrócie

Endpoint
POST /api/v1/workflows/{workflow_id}
Uwierzytelnianie
Klucz API Bearer
Przetwarzanie
Asynchroniczne — odpytuj endpoint statusu
Typowy czas
20–60 sec / image
Credits
4 credits w 2K · 5 credits w 4K
Proporcje obrazu
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limity wejściowe
Do 10 MB na obraz; JPEG, PNG, WebP
Idempotentne
Nie

Żądanie i odpowiedź

Żądanie

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

Parametry żądania

workflow_id

Typ: stringWymagane

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

images

Typ: objectWymagane

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

Wartości: 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

Wartości: 2K4K

Błędy

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.

Limity

  • 600 żądań na minutę na klucz API (Stałe okno czasowe; limit jest taki sam w każdym planie)
  • Odpowiedź 429 zawiera nagłówek Retry-After: 30 s
  • Do 10 MB na obraz
  • Formaty: JPEG, PNG, WebP
  • Jednoczesne zadania wsadowe w zależności od planu: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Tylko polling — API nie wysyła webhooków.

Pobierz katalog, wypełnij sloty, uruchom

Wylistuj workflows, wypełnij ich zadeklarowane sloty, wyślij żądanie, odpytuj o każdy element, pobierz.

  1. Krok 1

    Wygeneruj klucz API

    Workflows używają tych samych danych uwierzytelniających i tego samego salda credits, co każda inna możliwość Photta.

  2. Krok 2

    Pobierz listę z katalogu workflow

    GET `/api/v1/workflows` zwraca 53 szablony z 7 kategorii, z których każdy deklaruje własne sloty na zdjęcia, enumy opcji i domyślny współczynnik proporcji. Filtruj za pomocą `category` — nieznana kategoria zwraca 400, zamiast zostać zignorowana.

  3. Krok 3

    Wyślij żądanie uruchomienia (POST)

    Wyślij POST `/api/v1/workflows/:workflow_id` z `images` (mapowanie slot id na zdjęcia) oraz `options` (mapowanie option id na choice id), pobranymi z wpisu w katalogu. `user_text` przyjmuje dowolny tekst żądania stylizacji, a `num_images` pozwala wygenerować od 1 do 4 zdjęć w jednym wywołaniu.

  4. Krok 4

    Odpytuj o każdy element

    Odpowiedź 202 zawiera jeden element na każde żądane zdjęcie. Wykonuj GET `/api/v1/workflows/generations/:id` co 3 sekundy dla każdego id, dopóki `data.status` nie przyjmie wartości `completed` lub `failed`; typowy czas ukończenia wynosi od 20 do 60 sekund na zdjęcie.

  5. Krok 5

    Pobierz i zapisz

    Każdy ukończony element zawiera własny `output_url`. Elementy kończą przetwarzanie niezależnie, więc możesz opublikować pierwszy, podczas gdy reszta wciąż się renderuje.

Pytania zadawane przez programistów przed uruchomieniem workflows

Czym jest workflows API?

To katalog gotowych szablonów scen, które uruchamiasz na własnych fotografiach produktów. Zamiast budować prompt, wybierasz workflow i wypełniasz sloty na zdjęcia oraz zadeklarowane opcje.

Ile kosztuje uruchomienie workflow?

4 credits za zdjęcie w 2K i 5 za zdjęcie w 4K, pomnożone przez `num_images`. Katalog zawiera aktualną cenę dla każdego workflow — odczytuj ją stamtąd, zamiast zakładać wartości z góry.

Jak znaleźć workflow id?

GET `/api/v1/workflows`. Każdy wpis zawiera swój id, kategorię, sloty na zdjęcia oraz opcje. Filtruj listę za pomocą parametru `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` lub `watch`.

Co powinno znaleźć się w images i options?

`images` mapuje slot id z wpisu w katalogu na tablicę zdjęć jako adresy https URL lub URI danych base64. `options` mapuje option id na jedno z pól choice id danej opcji. Obie struktury pochodzą z katalogu, dzięki czemu integracja pozostaje aktualna przy dodawaniu nowych workflows.

Ile zdjęć można wygenerować w ramach jednego uruchomienia?

`num_images` przyjmuje wartości od 1 do 4. Każde zdjęcie jest generowane niezależnie i otrzymuje własny item id w odpowiedzi, więc błąd jednego nie wpływa na pozostałe.

Jak odpytywać o wyniki?

Odpytuj każdy element osobno: GET `/api/v1/workflows/generations/:id` co 3 sekundy. GET `/api/v1/workflows/generations/list` zwraca widok stronicowany, filtrowany według `workflow_id` lub `status`.

Powiązane możliwości

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono

Wypróbuj API w 5 minut

Wygeneruj klucz Photta API, wklej powyższy snippet cURL, a otrzymasz swoje pierwsze zdjęcie na modelu, zanim zaparzy się kawa.

  • 20–60 sec / image
  • 4 credits w 2K · 5 credits w 4K
  • asynchroniczne, polling
  • 600 requests/min
  • Klucz Bearer