Templates

Templates are the foundation of Mockupanda. This page explains how to find, use, and understand templates.

What is a Template?

A template is a pre-designed mockup scene with designated frame(s) for your artwork, and metadata like frame ratio, blending mode etc. When using the API, your artwork is automatically placed into the frame(s) and rendered into the scene, with the artwork set to fill the frame(s).

Finding Templates

Template IDs

Each template has a unique ID. Use this ID in the template_id parameter when generating mockups. Visit mockupanda.com/editor to browse all available templates and copy their IDs. Filter by:

API Endpoint

Fetch all templates programmatically:

curl -X GET https://www.mockupanda.com/api/v1/templates \
-H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Default	Description
`type`	string	-	Filter by template type: `"print"` for wall-art/poster templates, `"product"` for apparel, mugs, and other 3D product templates. Omit to return all types.
`category`	string	-	Filter by category (e.g., "Wall Art", "Devices")
`search`	string	-	Search by name (case-insensitive)
`page`	integer	`1`	Page number
`limit`	integer	`50`	Items per page (max `100`)

Response:

{
  "templates": [
    {
      "id": "bedroom-poster-01",
      "name": "Bedroom Poster",
      "category": "poster",
      "frame_count": 1,
      "thumbnail_url": "https://pub-2702811b4e0b4173a4fd7e0de9e0b474.r2.dev/thumbnails/bedroom-poster-01.jpg",
      "aspect_ratio": 0.67,
      "blending_mode": "normal",
      "render_mode": "corners",
      "surface_type": null,
      "is_product_template": false
    },
    {
      "id": "wall-diptych-01",
      "name": "Wall Diptych",
      "category": "wall-art",
      "frame_count": 2,
      "thumbnail_url": "https://pub-2702811b4e0b4173a4fd7e0de9e0b474.r2.dev/thumbnails/wall-diptych-01.jpg",
      "aspect_ratio": 0.67,
      "blending_mode": "normal",
      "render_mode": "corners",
      "surface_type": null,
      "is_product_template": false
    },
    {
      "id": "tshirt-flat-01",
      "name": "T-Shirt Flat Lay",
      "category": "apparel",
      "frame_count": 1,
      "thumbnail_url": "https://pub-2702811b4e0b4173a4fd7e0de9e0b474.r2.dev/thumbnails/tshirt-flat-01.jpg",
      "aspect_ratio": 1.0,
      "blending_mode": "multiply",
      "render_mode": "uvmap",
      "surface_type": "fabric",
      "is_product_template": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 120,
    "total_pages": 3
  },
  "categories": ["apparel", "devices", "poster", "wall-art"]
}

Response Fields

Each template in the response includes:

Field	Type	Description
`id`	string	Unique template identifier
`name`	string	Display name
`category`	string	Template category
`frame_count`	integer	Number of artwork frames
`thumbnail_url`	string \| null	Thumbnail image URL
`aspect_ratio`	number	Expected artwork aspect ratio as a decimal (e.g., 0.67 for portrait 2:3, 1.0 for square, 1.5 for landscape 3:2)
`blending_mode`	string	Blend mode used when compositing artwork: `"normal"`, `"multiply"`, `"screen"`, etc.
`render_mode`	string	How the artwork is rendered: `"corners"` (perspective warp) or `"uvmap"` (UV-mapped product surface)
`surface_type`	string \| null	Material hint for product templates (e.g., "fabric"). Null for print templates.
`is_product_template`	boolean	True for apparel, mugs, and other 3D product templates. False for flat print/poster templates.

The response also includes a pagination object (page, limit, total, total_pages) and a categories array listing all available category names.

Template Properties

Single-Frame Templates

Most templates have one frame. Use artwork_url to specify the artwork:

curl -X POST https://www.mockupanda.com/api/v1/mockups/generate \
--http1.1 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "template_id": "bedroom-poster-01",
  "artwork_url": "https://example.com/art.jpg"
}'

Multi-Frame Templates

Some templates have multiple frames (diptych, triptych). Use artwork_urls to map frame indices to artwork:

curl -X POST https://www.mockupanda.com/api/v1/mockups/generate \
--http1.1 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "template_id": "wall-diptych-01",
  "artwork_urls": {
    "0": "https://example.com/art1.jpg",
    "1": "https://example.com/art2.jpg"
  }
}'

Frame indices start at 0. If a template has 3 frames, use "0", "1", and "2".

Aspect Ratios

Each template expects a specific artwork aspect ratio:

Portrait (2:3): 2000x3000, 1000x1500, etc.
Square (1:1): 2000x2000, 1500x1500, etc.
Landscape (3:2): 3000x2000, 1500x1000, etc.

The API will crop artwork to fit the template's ratio. Preview the template to see the expected ratio.

Template Updates

We regularly add new templates. Existing template IDs never change — your integration won't break when we add new templates.