Sign inGet started

API reference

Base URL https://productaura.co/api/v1. Send Authorization: Bearer pa_… (Settings → API keys). Errors are JSON { error, message }. 1 credit = one 2K image; reading calls are free. Rate limit: 120 requests per minute per account. Machine-readable: openapi.json. Overview and CLI: API and CLI.

Packs, shots, languages and prices

GET /api/v1/catalog · no API key needed

Lists the platform packs with each shot and its credit cost, the languages for on-image text, plans and credit packs. No API key needed.

Cost: Free

Response 200

{
  "packs": [
    {
      "id": "amazon",
      "label": "Amazon listing",
      "shots": [
        {
          "key": "main-white",
          "credits": 1
        }
      ]
    }
  ]
}

Your e-mail and credit balance

GET /api/v1/me

Returns the account the key belongs to and its credit balance (1 credit = one 2K image).

Cost: Free

Response 200

{
  "email": "[email protected]",
  "balance": 20,
  "creditMeaning": "1 credit = one 2K image"
}

Signed URL for a direct photo upload

POST /api/v1/uploads

Returns a signed URL; PUT the photo bytes to it with the same Content-Type, then pass uploadId to POST /products. Use this for photos over a few MB.

Cost: Free

Request body

{
  "contentType": "image/jpeg",
  "size": 2400000
}

Response 200

{
  "uploadId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
  "uploadUrl": "https://…",
  "method": "PUT",
  "headers": {
    "Content-Type": "image/jpeg"
  }
}

Errors: 400

Create a product from a photo

POST /api/v1/products

Stores the photo and analyses it into a product profile (name, features, setting) that fills the prompts. Send imageBase64 or an uploadId. Takes a few seconds.

Cost: Free

Request body

{
  "imageBase64": "/9j/4AAQSkZJRg…",
  "name": "Soy candle"
}

Response 201

{
  "product": {
    "id": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
    "name": "Soy wax candle in amber jar"
  }
}

Errors: 400, 404

Your products

GET /api/v1/products

Lists your products (newest first, up to 100) with their folder and image sets.

Cost: Free

Response 200

{
  "products": [
    {
      "id": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
      "name": "Soy candle",
      "folder_id": null,
      "image_sets": [
        {
          "id": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
          "pack": "amazon"
        }
      ]
    }
  ]
}

Move a product to a folder

POST /api/v1/products/{id}/move

Puts the product in a folder, or takes it out of every folder with folderId null.

Cost: Free

Request body

{
  "folderId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b"
}

Response 200

{}

Errors: 404

Your folders

GET /api/v1/folders

Lists your folders in tree order, each with its parent and product count.

Cost: Free

Response 200

{
  "folders": [
    {
      "id": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
      "name": "Store 1",
      "parentId": null,
      "kind": "store",
      "products": 3
    }
  ]
}

Create a folder

POST /api/v1/folders

Creates a folder, optionally inside another one.

Cost: Free

Request body

{
  "name": "Client: Acme"
}

Response 201

{
  "folder": {
    "id": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
    "name": "Client: Acme",
    "parentId": null
  }
}

Errors: 400, 404

Plan an image set

POST /api/v1/image-sets

Creates an image set for a product, platform pack and language, and returns the shot plan with the credit cost of each shot. Nothing is generated yet.

Cost: Free

Request body

{
  "productId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
  "pack": "amazon",
  "locale": "de"
}

Response 201

{
  "imageSetId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
  "balance": 20
}

Errors: 400, 404

Generate the images

POST /api/v1/image-sets/{id}/generate · send an Idempotency-Key header

Spends credits and queues the chosen shots, all or nothing (default: the plan’s default shots). Returns at once; images take about 1–3 minutes. Send an Idempotency-Key so a retry never charges twice.

Cost: The sum of the shots’ credits (usually 1 per image)

Request body

{
  "shots": [
    "main-white",
    "infographic-features",
    "lifestyle"
  ]
}

Response 202

{
  "generationIds": [
    "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b"
  ],
  "balance": 17,
  "status": "queued"
}

Errors: 400, 402, 404, 503

Status and images

GET /api/v1/image-sets/{id}

Returns every image with its status and signed URLs (valid 15 minutes). Poll every few seconds until done is true.

Cost: Free

Response 200

{
  "done": true,
  "pending": 0,
  "imageSet": {
    "id": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
    "pack": "amazon",
    "generations": [
      {
        "id": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
        "shotKey": "main-white",
        "status": "done"
      }
    ]
  }
}

Errors: 404

Check against platform rules

GET /api/v1/image-sets/{id}/checks

Checks the newest finished version of each image against the platform’s published rules: Amazon main image, sizes, formats, Etsy’s 1 MB warning, Shopify limits.

Cost: Free

Response 200

{
  "pack": "amazon",
  "set": [],
  "images": [
    {
      "shotKey": "main-white",
      "checks": [
        {
          "status": "pass",
          "text": "Pure white background (RGB 255, 255, 255)"
        }
      ]
    }
  ]
}

Errors: 404

Edit an image with a sentence

POST /api/v1/generations/{id}/edit · send an Idempotency-Key header

Changes one finished image as described ("warmer light, add a marble counter") and keeps the product and everything else. The result is a new version; the old one stays.

Cost: One image (usually 1)

Request body

{
  "instruction": "warmer light, add a marble counter"
}

Response 202

{
  "generationId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
  "imageSetId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
  "cost": 1,
  "balance": 16,
  "status": "queued"
}

Errors: 400, 402, 404, 409, 503

Make an image again

POST /api/v1/generations/{id}/regenerate · send an Idempotency-Key header

Makes the same shot again with the same prompt, as a new version. Not for the main image on white (a cut-out of your photo); edit that one instead.

Cost: One image (usually 1)

Response 202

{
  "generationId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
  "imageSetId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
  "cost": 1,
  "balance": 15,
  "status": "queued"
}

Errors: 400, 402, 404, 409, 503

Rate an image

POST /api/v1/generations/{id}/rating

Thumbs up (1), down (-1) or clear (null), with optional reasons: product-changed, wrong-text, not-realistic, bad-composition, wrong-style, low-quality.

Cost: Free

Request body

{
  "rating": -1,
  "reasons": [
    "wrong-text"
  ]
}

Response 200

{}

Errors: 400, 404

Send feedback

POST /api/v1/feedback

Sends a message to the Product Aura team.

Cost: Free

Request body

{
  "message": "The German callouts are great."
}

Response 201

{}

Errors: 400

Payment link for credits

POST /api/v1/checkout

Returns a Stripe payment link for a credit pack or a plan. A person opens it and pays; nothing is charged by this call. Without an API key it returns the card links for buying credits without an account (the page after payment shows a key).

Cost: Free

Request body

{
  "kind": "pack",
  "pack": "pack_m"
}

Response 200

{
  "url": "https://checkout.stripe.com/…"
}

Errors: 400, 503