ProductAIDocs
Get API Key

Partner API

Partner API

For agencies and platforms that produce product photos for many brands: bring in a catalogue, shoot it in brand scenes, check every image against the real product, and deliver it in each brand's format.

Access is switched on per account

The Partner API answers 404 to every key until we turn it on for your account. Apply for the partner programme and we set you up with a test budget.

How it works

Text
1. Products   PUT /partner/products/:id   or   POST /partner/feeds  (XML feed)
2. Brands     PUT /partner/brands/:id     (colors, voice, output spec)
3. Scenes     POST /partner/scenes        (your prompt, or a ProductAI template)
4. Run        POST /partner/runs          (products × scenes, for a brand)
5. Check      every image gets a fidelity verdict
6. Review     approve / reject with a note, or share the review link
7. Deliver    POST /partner/runs/:id/download  (zip in the brand's output spec)
              + webhooks for every image and run

Basics

  • Base URL https://api.productai.photo/v1, header x-api-key with a key from API access.
  • Responses are { "status": "OK", "data": … }; errors { "error": "…" } with a 4xx or 5xx.
  • 300 requests a minute per account.
  • Products, brands and runs are keyed by your ids, so every write is safe to retry.
  • GET /partner/account returns your balance, the models with their price per image, and your webhook.

Quality

The fidelity check

Every image is compared with the product photos by a vision model: did the label, text, colour, shape, a part or the size change? Each image comes back ok or flagged with a category and a one-line note, before anyone reviews it.

Pairs, worn products and small text

A feed usually shows one shoe. Ask for a pair or a shot on a foot and a model has to invent the other side. Small embossed or printed text is the other known risk. Tell us about both and every prompt handles them:

  • sold_as: "pair" makes the second shoe the mirror image of the photographed one and keeps the photographed side towards the camera. Footwear from a feed gets it automatically. Send the second shoe or the inside as an extra image when you have it.
  • exact_text: "Calvin Klein" quotes the text letter for letter and forbids inventing letters; the fidelity check holds the render to it. A close-up of the text as an extra image helps most.

When the automated flow is not enough

Some products need a person: shoes on feet from a one-shoe photo, apparel on a model, worn jewellery, glass and chrome. An image that fails the fidelity check twice, or a product you mark for the studio, goes to our studio queue instead of being redone again. We fix it with a better reference or quote it, and the result comes back into the same run and review link. Turnaround for both tracks is agreed per partner; a new vertical starts with a free test of 10 products.

Webhooks

PUT /partner/webhook { "url": "https://…" } returns a signing secret. We send item.completed, item.failed, item.reviewed and run.completed; a delivery without a 2xx is retried a minute later. Verify the ProductAI-Signature: t=…,v1=… header and reject anything older than 5 minutes.

Verify a webhook (Node.js)
const [t, v1] = header.split(',').map((p) => p.split('=')[1]);
const expected = crypto
  .createHmac('sha256', secret)
  .update(`${t}.${rawBody}`)
  .digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));