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
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')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "completed",
"output_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508-thumb.jpg",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z",
"completed_at": "2026-08-03T10:20:41Z",
"error_code": null,
"error_message": null
},
"request_id": "req_wfl003"
}Parametri della richiesta
workflow_idTipo: stringObbligatorio
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
imagesTipo: 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.
optionsTipo: 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_textTipo: 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_imagesTipo: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratioTipo: 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:9resolutionTipo: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Valori:2K4K
Errori
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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.
Passaggio 1
Genera una chiave API
I workflow utilizzano le stesse credenziali e lo stesso saldo di credits di qualsiasi altra funzionalità di Photta.
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.
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.
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.
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.
Lo stesso endpoint in Node.js, Python e cURL
Node.js
Workflows API in Node.js
Chiama workflows API di Photta da un backend Node.js con fetch nativo. Nessun SDK richiesto: salva la chiave, invia il job, esegui il polling per il risultato.
LeggiPython
Workflows API in Python
Chiama la workflows API di Photta in Python con la libreria requests. Wrapper di trenta righe, compatibile con async tramite httpx, funziona in Django, FastAPI e Celery.
LeggicURL
Workflows API con cURL
Chiama workflows API di Photta direttamente dalla shell con cURL. Invia, effettua il polling, scarica — ogni snippet si integra con jq per pipeline basate su script.
Leggi
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
Funzionalità
API di Virtual try-on per abbigliamento
REST API per applicare capi di abbigliamento su manichini AI. Generazione asincrona in 1.5–4 minuti, 5 crediti a 2K, 6 a 4K. Esempi per cURL, Node.js e Python.
Vedi l'endpointFunzionalità
API try-on per gioielli per collane, anelli, bracciali e orecchini
Applica collane, anelli, bracciali e orecchini su modelli AI tramite REST. 5 credits a 2K, manichini in primo piano integrati, rendering con gestione dei riflessi dalla documentazione di Photta.
Vedi l'endpointSviluppa
Crea un servizio di fotografia di prodotto basato su AI
La guida per i founder per rivendere l'API di virtual try-on di Photta come SaaS white-label: tenant key, fanout in batch, fatturazione per credits, realtà degli SLA.
Vedi l'endpointConfronta
Photta vs Ayna — API per sviluppatori o studio incentrato su Shopify
Confronto tra Photta e Ayna: tre endpoint REST contro uno studio nativo per Shopify con API. Entrambi hanno punti di forza. Dati estratti dai rispettivi siti il 2026-04-19.
Vedi l'endpointGuida rapida
La prima immagine con Photta in meno di cinque minuti.
Registrati, genera una chiave API, esegui la tua prima chiamata cURL, fai polling fino al completamento, salva il risultato. Cinque passaggi, interamente documentati.
Vedi l'endpointRiferimento
Errori delle API di Photta
L'elenco completo dei tipi di errore delle API di Photta con i relativi codici di stato, la struttura del payload di errore e quali fallimenti ha senso riprovare.
Vedi l'endpointRiferimento
Rate limit delle API Photta
Il rate limit delle API Photta, la relativa finestra, l'header Retry-After, l'intervallo di polling e i limiti di concorrenza per piano, tutti desunti dalla documentazione delle API.
Vedi l'endpoint
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