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
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"]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')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 / 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"
}{
"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"
}Request-parametre
workflow_idType: stringPåkrævet
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
imagesType: 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.
optionsType: 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_textType: 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_imagesType: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratioType: 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:9resolutionType: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Værdier:2K4K
Fejl
- 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.
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.
Trin 1
Generér en API-nøgle
Workflows bruger de samme legitimationsoplysninger og den samme credits-saldo som alle andre Photta-kapabiliteter.
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.
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.
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.
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.
Det samme endpoint i Node.js, Python og cURL
Node.js
Workflows API i Node.js
Kald Phottas workflows API fra en Node.js-backend med indbygget fetch. Ingen SDK påkrævet: gem din nøgle, indsend jobbet, foretag polling for resultatet.
LæsPython
Workflows API i Python
Kald Phottas workflows API i Python med requests-biblioteket. Tredive-linjers wrapper, async-venlig via httpx, fungerer i Django, FastAPI og Celery.
LæscURL
Workflows API med cURL
Kald Phottas workflows API direkte fra kommandolinjen med cURL. Indsend, poll, download — hvert kodestykke fungerer sammen med jq til scriptede pipelines.
Læs
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
Funktioner
Virtuel try-on API til tøj
REST API, der placerer tøj på AI-mannequiner. Asynkront, 1.5–4 minutters generering, 5 credits ved 2K, 6 ved 4K. cURL-, Node.js- og Python-eksempler.
Se endpointetFunktioner
Try-on-API til smykker til halskæder, ringe, armbånd og øreringe
Placér halskæder, ringe, armbånd og øreringe på AI-modeller via REST. 5 credits ved 2K, indbyggede close-up-mannequiner, refleksionsbevidst rendering fra Photta-dokumentationen.
Se endpointetByg
Byg en AI-produktfotograferingstjeneste
En playbook til stiftere om videresalg af Phottas virtuelle try-on-API som en white-label-SaaS: tenant-nøgler, batch-fanout, fakturering pr. credit, SLA-realiteter.
Se endpointetSammenlign
Photta mod Ayna — udvikler-API eller Shopify-først studie
Photta vs. Ayna sammenlignet: tre REST-endpoints vs. et Shopify-fokuseret studie + API. Begge har styrker. Hentet fra hver side den 2026-04-19.
Se endpointetHurtig start
Første Photta-billede på under fem minutter.
Opret en konto, generer en API-nøgle, kør dit første cURL-kald, foretag polling indtil det er fuldført, gem resultatet. Fem trin, dokumenteret fra start til slut.
Se endpointetReference
Photta API-fejl
Den komplette liste over Photta API-fejltyper med deres statuskoder, strukturen på fejlsvaret, og hvilke fejl det kan betale sig at prøve igen.
Se endpointetReference
Photta API rate limits
Photta API-rate limit, dets vindue, Retry-After-headeren, polling-intervallet og lofterne for samtidighed pr. abonnement, alt sammen aflæst fra API-dokumentationen.
Se endpointet
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