Quickstart

Generate mockups via the REST API in minutes. This guide walks you through making your first API request.

Prerequisites

Before you begin, make sure you have:

  1. A Mockupanda account (sign up here)
  2. An API key from DashboardAPI keys
  3. A template ID from DashboardTemplates. Add one from the library or create your own, then copy its ID from the card.

New accounts start with free credit for their first mockups. Top up any time from DashboardBilling.

Generate Your First Mockup

Replace YOUR_API_KEY and TEMPLATE_ID with your actual values:

const response = await fetch("https://www.mockupanda.com/api/v1/mockups/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template_id: "TEMPLATE_ID",
    artwork_url: "https://example.com/artwork.png",
    format: "jpeg",
    width: 2000,
  }),
});

if (!response.ok) {
  const error = await response.json();
  console.error(error.code, error.error);
  // e.g. "INSUFFICIENT_CREDITS", "Insufficient account balance..."
  return;
}

// Save the image
const blob = await response.blob();
const url = URL.createObjectURL(blob);
// Use the url in an <img> tag, or download it

What This Does

This request:

  • Authenticates using your API key
  • Selects the template specified by template_id
  • Downloads your artwork from artwork_url
  • Renders the artwork into the template
  • Returns the mockup image (JPEG or PNG)

Response

If successful, you'll receive a 200 OK response with the image binary. Save it to a file:

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",
  "format": "jpeg",
  "width": 2000
}' \
--output mockup.jpg

Or get JSON with the image as base64 instead:

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",
  "response_format": "json"
}'

Parameters

template_idTemplate to render (required)required
artwork_urlPublic URL of your artwork image (required)required
artwork_urlsSeveral frames: { "0": "url", "1": "url" }
format"jpeg" (default) or "png"
quality1 to 100 (default 85, JPEG only)
widthOutput width in px (default 2000, max 4000)
response_format"json" to get raw base64 instead of binary

Optional Parameters

  • format: "jpeg" (default) or "png". The output image format
  • quality: 1 to 100 (default 85). JPEG quality, higher means a larger file
  • width: Output width in pixels (default 2000, max 4000)
  • response_format: "binary" (default) or "json". Returns the image itself, or JSON with the image as base64 in an image field

Batch Generation (Multiple Templates)

Generate multiple mockups from one artwork in a single request. Use template_ids instead of template_id (max 12 templates). Requires response_format="json":

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_ids": ["bedroom-poster-01", "frame-wall-02", "living-room-03"],
  "artwork_url": "https://example.com/art.jpg",
  "response_format": "json"
}'

Batch Response:

{
"success": true,
"count": 2,
"total_size_bytes": 245678,
"results": [
  {
    "template_id": "bedroom-poster-01",
    "image": "/9j/4AAQSkZJRg...",
    "format": "jpeg",
    "content_type": "image/jpeg",
    "size_bytes": 523481
  },
  {
    "template_id": "frame-wall-02",
    "image": "/9j/4AAQSkZJRg...",
    "format": "jpeg",
    "content_type": "image/jpeg",
    "size_bytes": 498210
  }
]
}

Mockups With Several Frames

Some templates have multiple frames (e.g., diptych, triptych). Use artwork_urls instead:

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"
  }
}'

Responses

Success (200 OK)

Binary Response (default):

  • Content-Type: image/jpeg or image/png
  • Body: Image binary data

JSON Response (when response_format=json):

{
"success": true,
"image": "/9j/4AAQSkZJRg...",
"format": "jpeg",
"content_type": "image/jpeg",
"size_bytes": 523481,
"template_id": "bedroom-poster-01",
"duration_ms": 1460
}

Errors

All errors return JSON with an error message and code:

{
"error": "Insufficient account balance. Add funds in Billing to continue.",
"code": "INSUFFICIENT_CREDITS",
"details": { "required_cents": 1, "balance_cents": 0 },
"hint": "Top up your API wallet from Dashboard > Billing and retry."
}

See the Error Handling page for all error codes.

More Examples

Complete Implementation Examples

async function generateMockup() {
const response = await fetch('https://www.mockupanda.com/api/v1/mockups/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    template_id: 'bedroom-poster-01',
    artwork_url: 'https://example.com/art.jpg',
    width: 2000,
    format: 'jpeg'
  })
});

if (response.ok) {
  const blob = await response.blob();
  // Download or display the image
  const url = URL.createObjectURL(blob);
  console.log('Mockup ready:', url);
} else {
  const error = await response.json();
  console.error(`Error: ${error.code} - ${error.error}`);
}
}

generateMockup();

Next Steps