Templates

Browse and use pre-built templates (presets) for consistent image generation.

GET/v1/presets

List all available templates/presets. Includes both system templates and your custom templates.

Headers

Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Number of templates to return. Max: 100.
`offset`	integer	0	Number of templates to skip.
`category`	string	all	Filter by category: `lifestyle`, `studio`, `seasonal`, `custom`
`type`	string	all	Filter by type: `system`, `user`

Example Request

curl "https://api.productai.photo/v1/presets?category=lifestyle&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response (200 OK)

{
  "presets": [
    {
      "preset_id": "preset_marble_table",
      "name": "Marble Table",
      "description": "Product on elegant marble surface with soft lighting",
      "category": "lifestyle",
      "type": "system",
      "thumbnail_url": "https://cdn.productai.photo/presets/marble_table_thumb.jpg",
      "prompt": "Place the product on a white marble table with soft natural lighting, minimalist background",
      "recommended_models": ["nanobanana2", "nanobananapro"],
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "preset_id": "preset_outdoor_nature",
      "name": "Outdoor Nature",
      "description": "Natural outdoor setting with greenery",
      "category": "lifestyle",
      "type": "system",
      "thumbnail_url": "https://cdn.productai.photo/presets/outdoor_nature_thumb.jpg",
      "prompt": "Product in a natural outdoor setting with green plants and soft sunlight",
      "recommended_models": ["nanobanana2", "kontext-pro"],
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 45,
  "limit": 10,
  "offset": 0,
  "has_more": true
}

Response Fields

Field	Type	Description
`preset_id`	string	Unique identifier. Use this in the generate endpoint.
`name`	string	Display name of the template.
`description`	string	Brief description of the template style.
`category`	string	Template category.
`type`	string	`system` (built-in) or `user` (custom).
`prompt`	string	The prompt used by this template.
`recommended_models`	string[]	Models that work best with this template.

GET/v1/presets/{preset_id}

Get details for a specific template.

Example Request

curl "https://api.productai.photo/v1/presets/preset_marble_table" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response (200 OK)

{
  "preset_id": "preset_marble_table",
  "name": "Marble Table",
  "description": "Product on elegant marble surface with soft lighting",
  "category": "lifestyle",
  "type": "system",
  "thumbnail_url": "https://cdn.productai.photo/presets/marble_table_thumb.jpg",
  "preview_images": [
    "https://cdn.productai.photo/presets/marble_table_preview_1.jpg",
    "https://cdn.productai.photo/presets/marble_table_preview_2.jpg"
  ],
  "prompt": "Place the product on a white marble table with soft natural lighting, minimalist background",
  "recommended_models": ["nanobanana2", "nanobananapro"],
  "usage_count": 15420,
  "created_at": "2024-01-01T00:00:00Z"
}

Using Templates with Generate API

Pass the preset_id to the generate endpoint instead of a custom prompt:

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",
    "preset_id": "preset_marble_table"
  }'

You can also combine a template with additional prompt instructions:

{
  "model": "nanobanana2",
  "image_url": "https://example.com/product.jpg",
  "preset_id": "preset_marble_table",
  "prompt": "Add a small plant in the background"
}

Code Examples

Python

import requests

# List templates
response = requests.get(
    "https://api.productai.photo/v1/presets",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"category": "lifestyle", "limit": 10}
)
presets = response.json()["presets"]

# Generate with template
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",
        "preset_id": presets[0]["preset_id"]
    }
)
print(response.json())

JavaScript

// List templates
const presetsResponse = await fetch(
  "https://api.productai.photo/v1/presets?category=lifestyle&limit=10",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const { presets } = await presetsResponse.json();

// Generate with template
const generateResponse = 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",
    preset_id: presets[0].preset_id
  })
});
console.log(await generateResponse.json());

Generate API →Templates Guide →

Templates

Headers

Query Parameters

Example Request

Success Response (200 OK)

Response Fields

Example Request

Success Response (200 OK)

Using Templates with Generate API

Code Examples

Python

JavaScript

Related