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",
      "frames": 1,
      "thumbnail": "https://mockupanda.com/templates/bedroom-poster-01/thumb.jpg",
      "aspect_ratio": "2:3",
      "render_mode": "corners",
      "surface_type": null,
      "is_product_template": false,
      "tags": ["bedroom", "modern", "single"]
    },
    {
      "id": "wall-diptych-01",
      "name": "Wall Diptych",
      "category": "wall-art",
      "frames": 2,
      "thumbnail": "https://mockupanda.com/templates/wall-diptych-01/thumb.jpg",
      "aspect_ratio": "2:3",
      "render_mode": "corners",
      "surface_type": null,
      "is_product_template": false,
      "tags": ["wall", "diptych", "minimalist"]
    },
    {
      "id": "tshirt-flat-01",
      "name": "T-Shirt Flat Lay",
      "category": "apparel",
      "frames": 1,
      "thumbnail": "https://mockupanda.com/templates/tshirt-flat-01/thumb.jpg",
      "aspect_ratio": "1:1",
      "render_mode": "uvmap",
      "surface_type": "fabric",
      "is_product_template": true,
      "tags": ["t-shirt", "apparel", "flat-lay"]
    }
    // ... more templates
  ],
  "total": 120
}

Response Fields

Each template in the response includes:

Field	Type	Description
`id`	string	Unique template identifier
`name`	string	Display name
`category`	string	Template category
`frames`	integer	Number of artwork frames
`thumbnail`	string	Thumbnail image URL
`aspect_ratio`	string	Expected artwork aspect ratio (e.g., "2:3")
`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.

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 Metadata

Fetch detailed metadata for a specific template:

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