Generate Image

Generate AI-powered product images with custom backgrounds and styles.

POST/v1/generate

Creates a new image generation job. Returns a job ID that can be used to poll for results.

Request

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body Parameters

Parameter	Type	Required	Description
`model`	string	Yes	Model to use for generation. Options: `nanobanana2`, `nanobananapro`, `nanobanana`, `kontext-pro`, `kontext-max`, `seedream`, `gpt-high`
`image_url`	string	Yes*	URL of the product image. Either `image_url` or `asset_id` is required.
`asset_id`	string	Yes*	ID of a previously uploaded asset. Either `image_url` or `asset_id` is required.
`prompt`	string	Yes	Text description of the desired background/scene.
`preset_id`	string	No	ID of a template/preset to use instead of a custom prompt.
`num_images`	integer	No	Number of images to generate. Default: 1. Max: 4.
`aspect_ratio`	string	No	Output aspect ratio. Options: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`. Default: `1:1`
`webhook_url`	string	No	URL to receive a POST request when generation completes.

Example Request

curl -X POST "https://api.productai.photo/v1/generate" \
  -H "Authorization: Bearer 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",
    "num_images": 2,
    "aspect_ratio": "1:1"
  }'

Response

Success Response (202 Accepted)

{
  "job_id": "job_abc123xyz",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z",
  "estimated_time_seconds": 30,
  "model": "nanobanana2",
  "num_images": 2
}

Response Fields

Field	Type	Description
`job_id`	string	Unique identifier for the generation job. Use this to poll for results.
`status`	string	Job status: `pending`, `processing`, `completed`, `failed`
`created_at`	string	ISO 8601 timestamp of when the job was created.
`estimated_time_seconds`	integer	Estimated time to complete the job in seconds.
`model`	string	The model used for generation.
`num_images`	integer	Number of images being generated.

Error Responses

// 400 Bad Request - Missing required parameter
{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: prompt"
  }
}

// 401 Unauthorized - Invalid API key
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

// 402 Payment Required - Insufficient credits
{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. Required: 5, Available: 2"
  }
}

// 429 Too Many Requests - Rate limit exceeded
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "retry_after": 60
  }
}

Available Models

Model	Credits	Description
`nanobanana2`	5	Recommended. Best balance of quality and speed.
`nanobananapro`	8	Highest quality output for professional use.
`nanobanana`	3	Fast generation, good for previews.
`kontext-pro`	3	Context-aware generation with scene understanding.
`kontext-max`	3	Maximum context awareness for complex scenes.
`seedream`	3	Creative and artistic style generation.
`gpt-high`	8	GPT-powered high-fidelity generation.

Code Examples

Python

import requests

response = requests.post(
    "https://api.productai.photo/v1/generate",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "nanobanana2",
        "image_url": "https://example.com/product.jpg",
        "prompt": "Place the product on a marble table with soft lighting"
    }
)

data = response.json()
job_id = data["job_id"]
print(f"Job created: {job_id}")

JavaScript / Node.js

const response = await fetch("https://api.productai.photo/v1/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "nanobanana2",
    image_url: "https://example.com/product.jpg",
    prompt: "Place the product on a marble table with soft lighting"
  })
});

const data = await response.json();
console.log("Job created:", data.job_id);

Next Steps

After creating a generation job, use the Jobs API to poll for results:

View Jobs API documentation →