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:

A Mockupanda account (sign up here)
An API key from Dashboard → API Keys
Credits in your wallet from Dashboard → Billing
A template ID from the template browser

Generate Your First Mockup

Replace YOUR_API_KEY and TEMPLATE_ID with your actual values:

const response = await fetch("https://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://mockupanda.com/api/v1/mockups/generate \
-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 base64-encoded JSON instead:

curl -X POST https://mockupanda.com/api/v1/mockups/generate \
-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_urlsMulti-frame: { "0": "url", "1": "url" }

format"jpeg" (default) or "png"

quality1–100 (default 85, jpeg only)

widthOutput width in px (default 2000, max 4000)

response_format"json" to get base64 instead of binary

Optional Parameters

format: "jpeg" (default) or "png" - Output image format
quality: 1-100 (default 85) - JPEG quality, higher = larger file
width: Output width in pixels (default 2000, max 4000)
response_format: "binary" (default) or "json" - Return image or JSON with base64

Multi-Frame Mockups

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

curl -X POST https://mockupanda.com/api/v1/mockups/generate \
-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": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
"width": 2000,
"height": 1500,
"format": "jpeg"
}

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.

Next Steps

More Examples

Complete Implementation Examples

async function generateMockup() {
const response = await fetch('https://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();