How to Use the Mockupanda API's Batch Mode to Generate 12 Mockup Variations Per Design in a Single API Call

Generating mockups one at a time is fine when you're working with a handful of designs. But the moment you start scaling a print-on-demand catalog, the math stops working in your favor. If you have 50 designs and 12 mockup templates each, that's 600 separate API calls with a naive one-at-a-time approach. Render times stack up, your code gets messy, and you hit rate limits faster than you'd like.

That's exactly the problem Mockupanda's batch mode solves. With a single POST /mockups/generate request, you can pass up to 12 template IDs and get all the rendered variations back in one go. For developers building automated workflows, POD storefronts, or catalog management tools, this is the feature that makes the whole system scale.

This guide covers everything you need to know: how batch mode works under the hood, how to structure your request payload, how to handle the response, and some practical tips for keeping your workflow efficient and your costs low.

What Batch Mode Actually Does

Before jumping into code, it helps to understand what's happening when you send a batch request. The Mockupanda API endpoint is POST https://www.mockupanda.com/api/v1/mockups/generate. In a standard single-template request, you'd pass one template ID along with your artwork URL and get one rendered mockup image back.

In batch mode, you replace that single template reference with a template_ids array. The API processes all the templates you've listed against the same artwork in that single request, and the response contains rendered output for all of them.

The template_ids Parameter

The key to batch mode is the template_ids field. Instead of targeting one template, you pass an array of IDs, and the API renders your artwork into each one. The current limit is 12 templates per request.

Here's what a minimal batch request body looks like in JSON:

{
  "artwork_urls": ["https://your-cdn.com/your-design.png"],
  "template_ids": ["tmpl_001", "tmpl_002", "tmpl_003", "tmpl_004"]
}

You still supply your artwork via artwork_urls as an array (this also supports multi-frame templates like diptychs and triptychs, where you'd provide multiple URLs for each frame). The template_ids array drives the batch behavior.

Credit Usage in Batch Mode

One thing to be clear on before you start sending large batches: credits are charged per rendered mockup, not per API call. If you send one request with 12 templates, you consume 12 credits. At $0.01 per credit, that's $0.12 per batch. For scale, 1,000 mockups costs $10 regardless of how you batch them.

The good news is that failed requests cost zero credits. So if something goes wrong server-side, you're not penalized. This makes batch mode risk-friendly for testing.

Takeaway: Batch mode does not give you a discount on credit costs, but it dramatically reduces the number of API calls you need to make, which helps you stay within rate limits and simplifies your code significantly.

Setting Up Your First Batch Request

Let's get into actual implementation. The Mockupanda API docs provide code samples in cURL, JavaScript, Python, Node.js, and PHP. Below are practical examples for the most common environments.

cURL

For quick testing or shell scripts, cURL is your friend. Here's a batch request targeting four templates:

curl -X POST https://www.mockupanda.com/api/v1/mockups/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "artwork_urls": ["https://your-cdn.com/design.png"],
    "template_ids": ["tmpl_001", "tmpl_002", "tmpl_003", "tmpl_004"]
  }'

You'll get a JSON response back with rendered image URLs for each template you specified. Simple and clean for automation scripts or one-off batch jobs.

Python

Python is a common choice for catalog automation scripts. Here's a clean example using the requests library:

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://www.mockupanda.com/api/v1"

template_ids = [
    "tmpl_001",
    "tmpl_002",
    "tmpl_003",
    "tmpl_004",
    "tmpl_005",
    "tmpl_006"
]

payload = {
    "artwork_urls": ["https://your-cdn.com/design.png"],
    "template_ids": template_ids
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{BASE_URL}/mockups/generate",
    json=payload,
    headers=headers
)

if response.status_code == 200:
    mockups = response.json()
    for mockup in mockups:
        print(mockup["url"])
else:
    print(f"Error: {response.status_code}", response.text)

This is a solid foundation for any catalog automation script. You can wrap this in a loop over your designs list, chunk your templates into groups of 12, and process your entire catalog systematically.

JavaScript (Node.js)

For Node.js environments, including serverless functions or backend APIs:

const fetch = require('node-fetch');

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://www.mockupanda.com/api/v1';

async function generateBatchMockups(artworkUrl, templateIds) {
  const response = await fetch(`${BASE_URL}/mockups/generate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      artwork_urls: [artworkUrl],
      template_ids: templateIds
    })
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// Usage
generateBatchMockups(
  'https://your-cdn.com/design.png',
  ['tmpl_001', 'tmpl_002', 'tmpl_003']
).then(mockups => {
  mockups.forEach(m => console.log(m.url));
}).catch(console.error);

Takeaway: Whichever language you use, the core pattern is the same: one artwork URL, an array of up to 12 template IDs, and one API call. Get that pattern right and you can wrap it in whatever automation layer your workflow needs.

Discovering Templates to Include in Your Batch

Batch mode is most powerful when you've already curated the exact templates you want to use for each product type. The GET /templates endpoint is how you explore Mockupanda's template library and find the IDs you need.

Using the Templates Endpoint

The GET /templates endpoint supports several query parameters that make it practical to filter down to exactly what you need. The most useful for batch workflows are:

• q — a hybrid semantic search parameter for finding templates by description or style

• Aspect ratio filters, to match your design's proportions

• Artwork-matching filters, to surface templates suited to a specific design shape

A quick example to search for poster templates:

curl "https://www.mockupanda.com/api/v1/templates?q=minimalist+poster+wall+art" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes template metadata and IDs. The documented library has over 121 templates, so the search and filter options matter.

Organizing Templates With Sets

Once you've found the templates that work for a specific product type, the smart move is to save them as a Set. Sets are named, ordered groups of templates stored in your Mockupanda account. You can retrieve a set via GET /sets/{id} and pull all its template IDs programmatically.

Here's the workflow:

1. Use the web editor to browse templates and build a Set for each product type (e.g., "Square Wall Art," "Portrait Poster," "Apparel Front View")

2. Retrieve the set via API with GET /sets/{id}

3. Extract the template IDs from the response

4. Chunk them into groups of up to 12

5. Send batch generate requests for each chunk

This approach separates the curation work (done once in the UI) from the generation work (done programmatically at scale), which is a clean separation of concerns.

Takeaway: Build your template Sets in the web editor first. Then your automation script just needs to fetch a set, grab the IDs, and batch them in groups of 12. You won't need to hardcode template IDs everywhere in your codebase.

Handling the Response and Managing Output

Sending the request is only half the job. You also need to handle the response cleanly, especially when you're generating mockups for dozens or hundreds of designs.

Parsing Batch Response Data

The batch response returns an array of mockup objects, one per template ID you submitted. Each object includes the rendered image URL and metadata about the template used. In a well-structured script, you'd pair each result with the template ID it corresponds to and the design it was generated from, so you can map outputs back to the right listing.

A basic Python example of capturing and organizing results:

results = []

for design in your_designs_list:
    for chunk in chunked(your_template_ids, 12):  # chunk into max 12
        response = requests.post(
            f"{BASE_URL}/mockups/generate",
            json={
                "artwork_urls": [design["url"]],
                "template_ids": chunk
            },
            headers=headers
        )
        if response.ok:
            for mockup in response.json():
                results.append({
                    "design_id": design["id"],
                    "template_id": mockup["template_id"],
                    "mockup_url": mockup["url"]
                })

From there, you can push those URLs directly to your product listings, store them in a database, or download them as assets.

Rate Limits to Keep in Mind

The Mockupanda API has rate limits of 100 requests per minute and 10,000 requests per day per API key. With batch mode at 12 templates per request, you can generate up to 1,200 mockups per minute in theory. For most catalog operations, that's more than enough headroom.

If you're running a very large catalog generation job, add a small delay between requests and handle 429 responses with exponential backoff. A simple time.sleep(0.7) between requests in Python keeps you comfortably under the rate limit while still processing quickly.

Render times to account for: simple templates take 1 to 2 seconds, complex ones 2 to 4 seconds, and high-resolution 4000px outputs take 3 to 5 seconds. For batch requests with 12 templates, plan your timeout settings accordingly.

Takeaway: Structure your script to handle response data immediately per batch, not at the very end of a long run. That way, if something fails midway through a large job, you have a clean partial result set and can resume without regenerating everything.

Working With Multi-Frame Templates in Batch Mode

One of the more advanced features you can combine with batch mode is multi-frame template support. Some templates in the library are diptychs or triptychs, meaning they have two or three frames that display different panels of artwork or different designs side by side.

Supplying Multiple Artwork URLs

For multi-frame templates, you supply multiple entries in the artwork_urls array instead of just one. The first URL maps to the first frame, the second to the second frame, and so on.

{
  "artwork_urls": [
    "https://your-cdn.com/design-panel-1.png",
    "https://your-cdn.com/design-panel-2.png",
    "https://your-cdn.com/design-panel-3.png"
  ],
  "template_ids": ["tmpl_triptych_001", "tmpl_triptych_002"]
}

If you include a mix of single-frame and multi-frame templates in the same batch, make sure your artwork_urls array covers the maximum frame count required. Templates that only need one frame will just use the first URL.

Practical Uses for Multi-Frame Batches

Multi-frame batch requests are particularly useful for:

• Generating gallery wall bundle mockups where each panel shows a coordinating print

• Creating set listings for print collections sold together

• Showcasing before/after or complementary designs in a single listing image

This is niche functionality, but for sellers who specialize in coordinated print sets, it removes a workflow step that would otherwise require manual compositing in design software.

Takeaway: If your product catalog includes multi-panel sets or gallery wall bundles, build your artwork_urls arrays accordingly. Batch mode works just as cleanly with multi-frame templates as with single-frame ones.

Scaling a Full Catalog With Batch Mode

Let's put the whole picture together. If you're a developer building a catalog automation tool or a POD business owner with technical resources, here's how a full batch-mode workflow looks end to end.

The Full Automation Pattern

1. Curate your template Sets in the Mockupanda web editor, organized by product type and aspect ratio.

2. Fetch your set IDs via GET /sets and retrieve template IDs for each set via GET /sets/{id}.

3. Prepare your design list with artwork URLs hosted on a CDN or storage bucket. The max artwork file size is 20 MB, and accepted formats are JPEG, PNG, GIF, and WebP. Transparent PNG alpha is preserved.

4. Loop through each design, fetching the appropriate template set for its product type.

5. Chunk the template IDs into groups of up to 12 and fire batch POST /mockups/generate requests.

6. Collect rendered URLs from each response and store them mapped to the correct design and template.

7. Push to your storefront, whether that's uploading to Etsy listings, updating a Shopify product, or storing in your own database.

For a catalog of 100 designs with 12 templates each, that's 1,200 mockups generated in roughly 100 API calls, well within rate limits for a single batch run.

Checking Your Wallet Before Large Runs

Before kicking off a large batch job, it's good practice to check your API wallet balance via GET /billing/wallet. At $0.01 per mockup, a 1,200-mockup run costs $12. Top-ups can be made manually via the dashboard in any amount from $1.00 to $1,000.00, and credits never expire, so pre-loading is a reasonable strategy for predictable catalog operations.

Note that the API does not currently support auto-recharge or billing alerts, so building a balance check into the start of your automation script prevents jobs from dying partway through due to insufficient credits.

Takeaway: Treat your pre-run wallet check as a non-negotiable step in any large batch script. A two-line balance check at the start of your job saves you from partial results and wasted debugging time.

Getting Started With the API

If you haven't used the Mockupanda API yet, the access point is your dashboard. Navigate to Dashboard, then API Keys to generate your key. The API base URL is https://www.mockupanda.com/api/v1, and all requests require a Bearer token in the Authorization header.

The Starter plan is available at $48 billed yearly and includes 700 downloads per month on the web app, while the Pro plan at $84 billed yearly adds unlimited downloads and priority support. API credits are separate from plan downloads and work on the pay-as-you-go wallet system, so your API usage doesn't eat into your web app download quota.

For developers at POD businesses looking to embed mockup generation into a customer-facing workflow, the Lifetime plan at $129 is worth a look for web app access alongside API usage.

The full documentation, including endpoint references, parameter details, and additional code samples in cURL, JavaScript, Python, Node.js, and PHP, lives in the Mockupanda API docs. Start with a small batch of four or five templates to validate your setup before scaling to full catalog runs.

Batch mode is one of those features that seems like a minor convenience until you actually run the numbers on a real catalog operation. At that point it becomes the thing your entire automation architecture is built around.