Funzionalità · Workflow

Workflows API una chiamata, un preset

In sintesi

La Workflows API di Photta applica template di scena pronti all'uso alle immagini dei tuoi prodotti. Recupera il catalogo con una fetch, compila gli slot immagine e le opzioni del workflow, invia una POST ed effettua il polling di ciascun elemento restituito fino al completamento.

  • Tempo tipico: 20–60 sec / image
  • Credits: 4 credits a 2K · 5 credits a 4K
  • Elaborazione: asincrono, polling
  • Limiti: 600 richieste/min
  • Autenticazione: Chiave Bearer

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato

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

Panoramica

Panoramica

Endpoint
POST /api/v1/workflows/{workflow_id}
Autenticazione
API key Bearer
Elaborazione
Asincrona — effettua il polling dell'endpoint di stato
Tempo tipico
20–60 sec / image
Credits
4 credits a 2K · 5 credits a 4K
Rapporti d'aspetto
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limiti di input
Fino a 10 MB per immagine; JPEG, PNG, WebP
Idempotente
No

Richiesta e risposta

Richiesta

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 / Completato

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

Parametri della richiesta

workflow_id

Tipo: stringObbligatorio

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

images

Tipo: objectObbligatorio

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

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

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

Tipo: integer

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

= 1

aspect_ratio

Tipo: string

Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).

= 3:4

Valori: 3:41:14:39:1616:9
resolution

Tipo: string

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

= 2K

Valori: 2K4K

Errori

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.

Limiti

  • 600 richieste al minuto per API key (Finestra fissa; il limite è lo stesso per ogni piano)
  • Un 429 restituisce Retry-After: 30 secondi
  • Fino a 10 MB per immagine
  • Formati: JPEG, PNG, WebP
  • Batch simultanei per piano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Solo polling — l'API non invia webhook.

Recupera il catalogo con una fetch, compila gli slot ed esegui

Elenca i workflow, compila gli slot dichiarati, invia la richiesta, effettua il polling di ciascun elemento e scarica il risultato.

  1. Passaggio 1

    Genera una chiave API

    I workflow utilizzano le stesse credenziali e lo stesso saldo di credits di qualsiasi altra funzionalità di Photta.

  2. Passaggio 2

    Ottieni l'elenco del catalogo dei workflow

    Una richiesta GET a `/api/v1/workflows` restituisce i 53 template distribuiti su 7 categorie, ciascuno con i propri slot immagine, enum di opzioni e aspect ratio predefinito. Filtra con `category` — una categoria sconosciuta restituisce 400 anziché essere ignorata.

  3. Passaggio 3

    Invia l'esecuzione con una POST

    Esegui una POST su `/api/v1/workflows/:workflow_id` passando `images` (mappatura tra slot id e immagini) e `options` (mappatura tra option id e choice id), entrambi ricavati dalla voce del catalogo. `user_text` accetta indicazioni di stile in testo libero, mentre `num_images` consente di generare da 1 a 4 immagini con una sola chiamata.

  4. Passaggio 4

    Effettua il polling di ciascun elemento

    La risposta 202 include un elemento per ogni immagine richiesta. Esegui una GET su `/api/v1/workflows/generations/:id` ogni 3 secondi per ciascun id finché `data.status` non risulta `completed` o `failed`; il completamento richiede tipicamente da 20 a 60 secondi per immagine.

  5. Passaggio 5

    Scarica e salva

    Ogni elemento completato include il proprio `output_url`. L'elaborazione dei singoli elementi si conclude in modo indipendente, consentendoti di pubblicare il primo mentre gli altri sono ancora in fase di rendering.

Domande frequenti degli sviluppatori prima di integrare i workflow

Che cos'è la Workflows API?

Un catalogo di template di scena pronti all'uso da applicare alle fotografie dei tuoi prodotti. Invece di dover comporre un prompt, selezioni un workflow e ne compili gli slot immagine e le opzioni dichiarate.

Quanto costa l'esecuzione di un workflow?

4 credits per immagine a 2K e 5 per immagine a 4K, moltiplicati per `num_images`. Il catalogo riporta il prezzo aggiornato per ciascun workflow: leggilo direttamente da lì anziché fare stime a priori.

Come si individua l'id di un workflow?

Esegui una GET su `/api/v1/workflows`. Ogni voce riporta il proprio id, la categoria, gli slot immagine e le relative opzioni. Puoi filtrare l'elenco specificando `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` o `watch`.

Quali parametri vanno inseriti in images e options?

`images` mappa lo slot id presente nella voce del catalogo su un array di immagini, fornite come URL https o data URI in base64. `options` associa un option id a uno dei choice id disponibili per quell'opzione. Entrambe le strutture sono definite dal catalogo: questo garantisce che l'integrazione continui a funzionare all'introduzione di nuovi workflow.

Quante immagini può produrre una singola esecuzione?

`num_images` accetta valori da 1 a 4. Ciascuna immagine viene generata in modo indipendente e riceve il proprio item id nella risposta: l'eventuale errore su una di esse non compromette l'elaborazione delle altre.

Come si effettua il polling per i risultati?

Esegui il polling di ogni elemento separatamente: GET `/api/v1/workflows/generations/:id` ogni 3 secondi. GET `/api/v1/workflows/generations/list` restituisce una vista impaginata filtrata per `workflow_id` o `status`.

Funzionalità correlate

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato

Prova l'API in 5 minuti

Genera una chiave API di Photta, incolla lo snippet cURL qui sopra e otterrai la tua prima immagine con modello prima ancora che il caffè sia pronto.

  • 20–60 sec / image
  • 4 credits a 2K · 5 credits a 4K
  • asincrono, polling
  • 600 richieste/min
  • Chiave Bearer