ProductAIDocs
Get API Key

Partner API

Scenes, runs and review

A run photographs products in scenes for one brand. Every image is checked, reviewed and delivered in the brand's output spec.

POST/v1/partner/scenes

A scene is a shot you want, written for "the product" rather than one SKU; we adapt it to each product. reference_image_url is optional: the model sees it as a style reference. You can also use any ProductAI template id as a scene. GET /partner/scenes lists yours.

Request
curl -X POST "https://api.productai.photo/v1/partner/scenes" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Concrete plinth, hard light",
    "prompt": "The product on a raw concrete plinth, hard sunlight from the left, long shadow, bone background",
    "reference_image_url": "https://cdn.example.com/moodboard/plinth.jpg"
  }'

POST/v1/partner/runs

Body

productsstring[]required
Your product ids, up to 300.
scenesinteger[]required
Scene or template ids, up to 20.
brandstring
Your brand id. Its output spec fixes the aspect ratio and the download format.
modestringdefault: spread
spread: one fitting scene per product. all: every fitting scene. plan [{ "product", "scene" }] sets exactly which product gets which scene.
modelstring
One of the models in GET /partner/account.
external_idstring
Makes the request safe to retry: the same id returns the first run.
metadataobject
Anything you want back on the run and in webhooks.

The whole run is priced up front and refused when your balance cannot cover it; failed images are refunded. GET /partner/runs/{id} returns the run and its items: state, review, job.imageUrl and the fidelity verdict.

Request
curl -X POST "https://api.productai.photo/v1/partner/runs" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "external_id": "ck-ss27-batch-1",
    "brand": "ck-footwear",
    "products": ["CK-SNK-01", "CK-SNK-02"],
    "scenes": [90211, 90212],
    "model": "NANOBANANAPRO",
    "mode": "spread"
  }'

POST/v1/partner/runs/{id}/items/{item_id}/review

Approve or reject an image. A rejection's note goes into the redo's prompt; remember keeps a note on the product for every later prompt.

  • POST …/items/{item_id}/regenerate redoes one image (costs one image); POST /partner/runs/{id}/regenerate-rejected redoes all rejected ones.
  • run.reviewUrl is a page where someone without a login approves or rejects. Share it like a password.
  • POST /partner/runs/{id}/download { "review": "approved" } returns a zip in the brand's output spec.
  • POST /partner/runs/{id}/cancel and /resume.
Request
curl -X POST "https://api.productai.photo/v1/partner/runs/88/items/1201/review" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "review": "rejected",
    "note": "Heel logo is garbled",
    "remember": { "text": "Heel logo reads Calvin Klein in thin caps" }
  }'