API & Developer Guides

How to Authenticate and Make Your First Mockupanda API Call in Under 10 Minutes Using cURL

By Mockupanda9 min read
How to Authenticate and Make Your First Mockupanda API Call in Under 10 Minutes Using cURL

If you've been generating mockups one at a time in a browser, you already know the drill: upload design, pick template, download image, repeat. The Mockupanda API exists to break that loop. One HTTP request in, one rendered mockup out — and you can automate the whole thing.

This guide is for developers and technically minded sellers who want to call the API for the first time. By the end, you'll have a working cURL command that returns a real mockup image. No frameworks, no SDK setup, no lengthy configuration. Just a terminal and a few minutes.

What You Need Before You Start

The prerequisites here are genuinely minimal. You don't need a staging environment or a complicated local setup.

A Mockupanda Account and Some Starting Credits

You'll need a Mockupanda account to get an API key. New accounts come with free credits for their first mockups, so you can follow this entire guide without spending anything. When you do need to top up, credits are added manually through Dashboard → Billing. The pricing is straightforward: 1 credit equals $0.01, so $10 gets you 1,000 mockups. Credits never expire, which makes it easy to forecast your credit spend before you scale up.

cURL Installed on Your Machine

cURL comes pre-installed on macOS and most Linux distributions. On Windows, it's available in PowerShell 5.1 and later, or you can install it via the official cURL website. Run curl --version in your terminal to confirm it's available. If you see a version number, you're good to go.

A Template ID

Every mockup generation request needs a template ID. You can find template IDs in your Mockupanda dashboard under Dashboard → Templates. Add a template from the library, then copy its ID from the card. You can also fetch templates programmatically via the GET /templates endpoint, which is worth bookmarking for when you want to build a dynamic template picker inside your own app. For now, grab one ID from the dashboard and keep it handy.

Takeaway: Have your account ready, cURL confirmed in your terminal, and one template ID copied before moving on. Everything after this is just a few commands.

Creating and Securing Your API Key

Authentication for the Mockupanda API uses API keys as Bearer tokens. Each key is tied to your account and can be created, revoked, or rotated at any time — which gives you full control over access without needing to touch your account password.

Step-by-Step Key Creation

Here's the exact flow:

  1. Log in to your Mockupanda dashboard.

  2. Navigate to Dashboard → API Keys.

  3. Click "Create API Key".

  4. Give the key a descriptive name. Something like "Dev Environment" or "Production Server" works well — the name is just a label to help you identify the key later.

  5. Copy the generated key immediately. This is important: the full key value is only shown once at creation. If you close the page without copying it, you'll need to revoke it and generate a new one.

Your key will start with the prefix mpa_ followed by a string of characters. Hold onto it; you'll be pasting it into your cURL command shortly.

Understanding Key Properties

Each API key in your dashboard shows a few useful properties: its Name, the Created timestamp, a Last Used timestamp, and a Status of either Active or Revoked. The Last Used field is handy for auditing — if a key hasn't been used recently and you don't recognize it, you can revoke it without affecting your other keys.

If you're building a production integration, it's good practice to use separate keys for different environments. That way, revoking a compromised dev key doesn't affect your live workflow.

Takeaway: Create your key, copy it immediately, name it something meaningful, and store it somewhere secure like a password manager or environment variable. Never hardcode it in source files you'll commit to a public repository.

Understanding the Authorization Header

Before writing the cURL command, it helps to understand exactly how authentication works. Every request to the Mockupanda API must include an Authorization header formatted as a Bearer token.

The Header Format

The header looks like this:

Authorization: Bearer mpa_abcd1234efgh5678ijkl9012mnop3456

The Bearer prefix is required — the API won't accept the key without it. Replace everything after Bearer with your actual key. That's the entire authentication mechanism. There are no session tokens to refresh, no OAuth flows to implement, and no cookies to manage.

The base URL for all API requests is https://www.mockupanda.com/api/v1. Every endpoint you call will start with that string.

What Happens When Authentication Fails

The API returns clear error responses when something goes wrong with authentication. If you forget the Authorization header entirely, you'll get a 401 Unauthorized response with the body:

{
  "error": "Authorization header is required",
  "code": "MISSING_API_KEY"
}

If the key is present but wrong or revoked, the response looks like this:

{
  "error": "Invalid or revoked API key",
  "code": "INVALID_API_KEY"
}

Both are easy to diagnose. Missing header means you forgot to include it. Invalid key means either a typo or the key has been revoked in the dashboard.

Takeaway: Copy the header format exactly, including the Bearer prefix and a single space before your key. If you get a 401, check the error code — it tells you exactly which of the two problems you're dealing with.

Making Your First API Call

Now for the actual request. The endpoint you want is POST /mockups/generate. You'll send your template ID, a publicly accessible URL for your artwork, and your Authorization header.

The Basic cURL Command

Here's a minimal working request that generates a single mockup:

curl -X POST "https://www.mockupanda.com/api/v1/mockups/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "YOUR_TEMPLATE_ID",
    "artwork_url": "https://your-public-domain.com/your-design.png"
  }'

Replace YOUR_API_KEY with the key you created, YOUR_TEMPLATE_ID with the ID you copied from the dashboard, and the artwork_url with a publicly reachable URL to your design file. The artwork file must be reachable by the API server, so a local file path won't work here. If your design is in cloud storage like S3 or Cloudinary, paste that URL directly. The maximum artwork file size is 20 MB.

Reading the Response

A successful request returns a 200 OK with a JSON body. When you request a JSON response (response_format=json), you'll get back each rendered image as a base64-encoded JPEG string along with some metadata, in this shape:

{
  "success": true,
  "results": [
    {
      "template_id": "bedroom-poster-01",
      "image": "/9j/4AAQSkZJRg...",
      "format": "jpeg",
      "content_type": "image/jpeg",
      "size_bytes": 523481
    }
  ],
  "count": 1,
  "total_size_bytes": 523481,
  "duration_ms": 1840
}

The image field contains the base64-encoded mockup. You can decode it and write it to a file, or pipe it into whatever storage layer your workflow uses. The duration_ms field shows how long rendering took. For simple templates, expect 1 to 2 seconds. More complex scenes take 2 to 4 seconds, and if you request a 4000px output width, plan for 3 to 5 seconds.

Default output is 2000px wide at JPEG quality 85. If you want a larger output, you can request a width of up to 4000px.

Abstract arch and sun art print used as the demo artwork
Abstract arch and sun art print used as the demo artwork

Takeaway: Run the command, check that success is true, and inspect the duration_ms and size_bytes fields to get a feel for what your templates produce. If you get an error response, the code field will tell you exactly what went wrong.

Understanding Rate Limits and Credits

Once your first request works, the natural next step is sending more. Before you do, it's worth understanding the two constraints that govern API usage: rate limits and credit balance.

Rate Limits

The API allows 100 requests per minute and 10,000 requests per day per API key. Rate limiting uses a sliding window algorithm. Every request increments your counter, and the counter resets at the end of each window. If you hit the limit, you'll receive a 429 Too Many Requests response.

Every API response includes three headers that help you track your position:

Header

What It Tells You

X-RateLimit-Limit

Maximum requests allowed in the current window

X-RateLimit-Remaining

Requests you still have available right now

X-RateLimit-Reset

Unix timestamp when the window resets

Building logic around X-RateLimit-Remaining is especially useful when you're running bulk jobs. If remaining hits zero, your code can pause and wait for the reset rather than hammering the API with 429 errors.

Credits and What They Cost

Each successful mockup render costs 1 credit, which is $0.01. Failed requests cost 0 credits, so you won't be charged for a bad template ID or an authentication error. Your current balance is visible in the dashboard at Dashboard → Billing, and you can also check it programmatically via the GET /billing/wallet endpoint.

When you're ready to run larger jobs, the batch mode endpoint lets you pass up to 12 template IDs in a single request using the template_ids array, which is far more efficient than making 12 separate calls.

Takeaway: Watch the X-RateLimit-Remaining header in your responses, especially during bulk runs. Keep an eye on your wallet balance in the dashboard before kicking off large jobs.

Troubleshooting Common First-Call Issues

Most problems on a first API call come down to a small handful of causes. Here's how to work through them quickly.

Authentication Errors (401)

If you get a 401, check two things in order. First, confirm the Authorization header is present and starts with Bearer (with a space after it). Second, verify the key hasn't been revoked in Dashboard → API Keys. The code field in the error body tells you which problem it is: MISSING_API_KEY means the header wasn't sent, INVALID_API_KEY means the key itself is the issue.

Template Not Found Errors

If the API returns a template not found error, the most common cause is a typo in the template ID, so copy it directly from the dashboard card rather than typing it manually.

Artwork URL Problems

The artwork_url must be publicly accessible. If you're testing with a local file or a URL behind authentication, the API server can't fetch it and the request will fail. Use a public cloud storage URL, a CDN link, or a publicly shared file from a service like Dropbox or Google Drive with the sharing setting set to "anyone with the link."

The maximum file size is 20 MB. If your design file is larger, resize or compress it before sending. For print-on-demand work, a high-resolution PNG is usually well under that limit.

Rate Limit Errors (429)

If you hit a 429, check the X-RateLimit-Reset header in the response to see when your window resets. Then wait until that timestamp before retrying. Building an exponential backoff into any bulk script is good practice here.

Takeaway: Most first-call failures fall into three buckets: authentication, template ID, or artwork URL. Work through them in that order and you'll resolve the issue quickly. The error codes in the JSON response body are specific enough to point you straight at the fix.

What to Build Next

Once your first request returns a rendered mockup, you've done the hard part. The API surface from here is consistent: same authentication header, same base URL, same JSON response shape.

A natural next step is exploring the GET /templates endpoint to fetch and filter the template library programmatically, which opens the door to building dynamic workflows that pick templates based on artwork dimensions or category. From there, the Sets feature lets you group templates into named collections and render an entire set with a single set_id parameter, which is especially useful for sellers with consistent product lines.

Mockupanda's REST API is designed to fit into real production workflows without a lot of ceremony. The pricing is predictable at $0.01 per mockup, failed requests don't cost credits, and the rate limits are generous enough for most catalog-scale jobs. Getting your first call working is genuinely the biggest step.