Main processes

This page collects every supported integration flow in a nutshell. Each process has its own tutorial with copy-pasteable curl calls — start with the one that matches your situation.

Before you start: every flow requires a plugin installation and an API key bound to it — see Authentication for the step-by-step setup.

Two terms are enough to get going:

• Session (order) — one POST /jobs call: a shared configuration (style, scenery, model, aspect ratio) applied to one or more products. Identified by order_id.
• Packshot — a photo of the product on a clean, neutral background. A photo session can only be ordered for a product that has an approved packshot.

The full glossary lives on the overview page.

A. Photo session from an existing packshot

The shortest path to finished images: the merchant already has a product packshot, so you upload it, register it, and order a session right away.

1. POST /assets/upload      → temporary URL to upload the file
2. PUT <upload_url>         → send the packshot file
3. POST /packshots          → register the packshot (approved immediately)
4. POST /jobs               → order a photo session
5. webhook / GET /jobs/{id} → receive the finished images
6. POST /jobs/{id}/accept   → (optional) rate the results

Tutorial: session from a packshot →

B. Packshot from a plain shop photo

The merchant only has a regular product photo (e.g. taken with a phone). First you generate several packshot candidates, the merchant picks one, and once it's accepted you can order photo sessions. This is where the packshot approval requirement kicks in: a session for a product with no accepted packshot returns 422 packshot_not_approved.

1. POST /assets/upload + PUT      → upload the shop photo
2. POST /images                   → register the photo in the catalog
3. POST /jobs (job_type=packshot) → order N packshot candidates
4. POST /jobs/{id}/accept         → accept the chosen candidate
   POST /jobs/{id}/reject         → reject the others
5. POST /jobs                     → order a photo session

Tutorial: packshot from a photo →

C. Session parameters — style, scenery, model

Before you submit a session, show the merchant what they can choose. Five endpoints return the complete catalog: styles (presets) with thumbnails and galleries, models, sceneries, available AI models with credit costs, and aspect ratios. This data is everything you need to build a picker screen in your plugin.

GET /presets        → styles with thumbnails, galleries, and cost
GET /models         → models (account + marketplace)
GET /sceneries      → sceneries (account + marketplace)
GET /ai-models      → AI models available to the account's plan
GET /aspect-ratios  → aspect ratios (one default)

Tutorial: session parameters →

D. Many products at once

A whole catalog to photograph? One session accepts up to 100 products, and POST /jobs/batch takes up to 100 sessions in a single call (up to 5000 images in total). The response is HTTP 207: each session succeeds or fails independently of the others.

1. Prepare the sessions (products + configuration)
2. POST /jobs/batch  → up to 100 sessions at once
3. HTTP 207          → per-session result (accepted / failed)
4. Receive results via webhooks or polling

Tutorial: bulk sessions →

E. Receiving results

When a job finishes, we send a webhook to your installation's address — HMAC signed, with automatic retries and the option to re-send. If you'd rather not run a webhook endpoint, you can poll GET /jobs/{id}. Result download URLs are valid for at least 7 days; a fresh URL is one call away.

webhook (push)                  GET /jobs/{id} (pull)
  ├─ verify the HMAC signature    ├─ check the status
  ├─ respond 2xx                  └─ download outputs[].url
  └─ download outputs[].url
URL expired? → POST /jobs/{id}/refresh-url

Tutorial: receiving results →

F. Repeat session (regeneration)

The merchant wants more images in the same style, or wasn't happy with the previous round? Clone the session with one call — same configuration, optionally a different image count per product. A clone is a fresh start: ratings don't carry over and credits are charged anew.

1. POST /orders/{id}/clone  (Idempotency-Key header required)
   ├─ empty body            → same products and image counts
   └─ body with subjects[]  → new image counts per product
2. Receive results as in process E

Tutorial: repeat session →

Next steps

• Authentication — API keys and permissions, before you start.
• Endpoints — the full route list, once you know the processes.
• Error reference — every error code with its cause and fix.