API Reference

Generate Image

Generate AI-powered product images with custom backgrounds and styles. Creates an asynchronous generation job — poll the job or receive a webhook when it completes.

POST/v1/api/generate

Headers

x-api-keystringrequired

Your API key. Get it from the API Access page in the Studio.

Content-Typestringrequired

Must be application/json.

Body parameters

modelstringrequired

Model to use for generation. See available models below.

promptstringrequired

Text description of the desired background/scene.

image_urlstring | string[]required

Public URL(s) of your product image(s). We download and re-host them, so each URL must be publicly reachable, max 10MB, JPEG/PNG/ WebP. Pass an array to send multiple reference images (up to 5, or 10 for Seedream 5 models). Optional only for gpt-1.5 and gpt-2, which support pure text-to-image. Use the Upload Asset endpoint if your images aren't publicly hosted.

aspect_ratiostringdefault: SQUARE

SQUARE, LANDSCAPE, or PORTRAIT. Nano Banana models additionally accept direct ratios: 1:1, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16.

resolutionstringdefault: 2K

Output resolution — Nano Banana models only. One of 1K, 2K, 4K.

output_formatstringdefault: png

png or jpg.

Multiple reference images

Multi-image models (Nano Banana, Seedream, gpt-1.5/gpt-2) accept an array of URLs — useful for combining angles or adding style references. Single-image models use the first URL only.

Multi-image request body

{
  "model": "nanobananapro",
  "image_url": [
    "https://example.com/product-front.jpg",
    "https://example.com/product-side.jpg"
  ],
  "prompt": "Combine both angles into one lifestyle shot on a wooden desk"
}

Response fields

data.idinteger

Job ID. Poll GET /v1/api/job/{id} for the result.

data.statusstring

Job status: NOT_STARTED, RUNNING, COMPLETED, ERROR.

data.promptstring

The prompt used for this job.

Credits are charged on submit

Credits are deducted when the job is created. Generation runs asynchronously — typical jobs complete in 15-60 seconds.

Request

curl -X POST "https://api.productai.photo/v1/api/generate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nanobanana2",
    "image_url": "https://example.com/product.jpg",
    "prompt": "Place the product on a marble table with soft natural lighting and a minimalist background",
    "aspect_ratio": "SQUARE"
  }'

Response · 200 OK

{
  "status": "OK",
  "data": {
    "id": 287344,
    "status": "RUNNING",
    "prompt": "Place the product on a marble table with soft natural lighting and a minimalist background"
  }
}

Error responses

// 400 Bad Request - Missing required parameter
{
  "name": "ApiError",
  "message": "prompt is required",
  "details": "No description was given."
}

// 400 Bad Request - Not enough credits
{
  "name": "ApiError",
  "message": "OUT_OF_TOKENS",
  "details": "Not enough credits"
}

// 401 Unauthorized - Missing API key
{ "error": "API key is required" }

// 403 Forbidden - Invalid API key
{
  "error": "Invalid or inactive API key. Go to
  https://www.productai.photo/dashboard/api-access
  to generate a new API key."
}

// 429 Too Many Requests - Rate limit exceeded
{
  "error": "Too many generation requests from this IP,
  please try again after a minute."
}

Available models

Model	Credits	Reference images	Description
`nanobanana2`	5	up to 5	Recommended. Best balance of quality and speed.
`nanobananapro`	8	up to 5	Highest quality output for professional use.
`nanobanana`	3	up to 5	Fast generation, good for previews.
`seedream-5-pro`	8	up to 10	Seedream 5.0 Pro editing — highest quality.
`seedream-5-lite`	3	up to 10	Seedream 5.0 Lite editing — fast.
`seedream`	3	up to 5	Seedream 4.0 — creative and artistic styles.
`kontext-pro`	2	1	FLUX Kontext Pro — context-aware editing.
`kontext-max`	3	1	FLUX Kontext Max — maximum context awareness.
`gpt-2`	10	up to 5 (optional)	ChatGPT Image 2. Works without image_url (text-to-image).
`gpt-1.5`	10	up to 5 (optional)	ChatGPT Image 1.5. Works without image_url (text-to-image).
`gpt-high`	8	1	ChatGPT Image 1, high quality.
`gpt-medium`	3	1	ChatGPT Image 1, medium quality.
`gpt-low`	2	1	ChatGPT Image 1, low quality — cheap drafts.

Next steps

After creating a generation job, poll the Jobs API for the result, or set a webhook URL on the API Access page to be notified when it completes. For product videos, see the Generate Video API.