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 DashboardAPI keys
- 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 itWhat 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.jpgOr 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)requiredartwork_urlPublic URL of your artwork image (required)requiredartwork_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 binaryOptional Parameters
- format:
"jpeg"(default) or"png". The output image format - quality:
1to100(default85). JPEG quality, higher means a larger file - width: Output width in pixels (default
2000, max4000) - response_format:
"binary"(default) or"json". Returns the image itself, or JSON with the image as base64 in animagefield
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/jpegorimage/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();