Generate Mockup

The core endpoint for generating mockups. Renders your artwork into a template and returns the final image.

Endpoint

POST /api/v1/mockups/generate

Request

Headers

HeaderValueRequired
AuthorizationBearer YOUR_API_KEYYes
Content-Typeapplication/json or multipart/form-dataYes

Parameters

Required Parameters

ParameterTypeDescription
template_idstringSingle template to render. Required unless using template_ids or set_id. Find IDs at mockupanda.com/editor
artwork_urlstringJSON only. Public URL of your artwork image. Must be a valid HTTP/HTTPS URL. Required unless using artwork (multipart) or artwork_urls.
artworkfileMultipart only. Binary image file for templates with one frame. Use instead of artwork_url when uploading a file directly. Max 20 MB.

Note: Use template_id (single output), template_ids (batch output), or set_id (batch output from a saved set). You can still pair any of them with artwork_url/artwork or artwork_urls.

Optional Parameters

ParameterTypeDefaultDescription
template_idsstring[]NoneBatch mode. Generate multiple mockups from one artwork upload. Max 12 per request. Requires response_format="json".
set_idstringNoneRender every template in a saved set, in the order it was saved. Counts toward the same 12 template limit, and requires response_format="json" when the set holds more than one template.
formatstring"jpeg"Output format: "jpeg" or "png"
qualityinteger85JPEG quality, from 1 to 100. Higher means a larger file. PNG ignores this.
widthinteger2000Output width in pixels (max 4000)
response_formatstring"binary""binary" returns image bytes, "json" returns raw base64 in the image field
product_colorstringNoneRecolors the product (today a tee, hoodie or tote) on templates where supports_product_color is true, keeping the fabric's folds and shading. A six digit hex color like "#1f2a44", or "original" for the photo's own color. Other templates ignore it, so you can send it with a mixed batch. Omit it to use the color the template was saved with.

Parameters for Several Frames

For templates with multiple frames (diptych, triptych):

ParameterTypeDescription
artwork_urlsobject{"0": "url1", "1": "url2"}

Response

Success (200 OK)

Binary Response (default)

Returns the image directly as binary data.

Headers:

Content-Type: image/jpeg (or image/png)
Content-Length: <size_in_bytes>
X-Template-Id: <template_id>
X-Duration-Ms: <render_time_ms>

Body: Image binary data

JSON Response (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
}

Batch JSON Response (template_ids + response_format=json)

{
  "success": true,
  "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
    }
  ],
  "count": 2,
  "total_size_bytes": 1021691,
  "duration_ms": 2890
}

Error Responses

All errors return JSON with an error message, code, and optional details.

400 Bad Request

Invalid request parameters.

{
  "error": "template_id or template_ids is required",
  "code": "MISSING_TEMPLATE_ID"
}

401 Unauthorized

Authentication failed.

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

402 Payment Required

Insufficient credits.

{
  "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."
}

404 Not Found

Template doesn't exist.

{
  "error": "Template not found: invalid-template-id",
  "code": "TEMPLATE_NOT_FOUND",
  "details": {
    "missing_template_ids": ["invalid-template-id"]
  }
}

413 Payload Too Large

Artwork file exceeds 20 MB limit.

{
  "error": "Artwork file is too large (max 20 MB)",
  "code": "ARTWORK_FILE_TOO_LARGE"
}

500 Internal Server Error

Server error during rendering.

{
  "error": "Failed to render mockup",
  "code": "MOCKUP_GENERATION_FAILED"
}

See Error Handling for complete error code reference.

Examples

Basic Mockup

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"
}' \
--output mockup.jpg

Best Quality PNG

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": "png",
  "width": 4000
}' \
--output mockup.png

Mockup With Several Frames

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"
  }
}' \
--output mockup.jpg

Batch Mockups (Multiple Templates, One Artwork)

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

JSON Response

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

Response:

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

Artwork Requirements

Supported Formats

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • WebP (.webp)
  • GIF (.gif, first frame only)

File Size Limits

  • Maximum: 20 MB per artwork file
  • Recommended: Under 5 MB for faster processing

Image Dimensions

  • Minimum: 500px on shortest side recommended
  • Recommended: 2000px or larger for best quality

Artwork URL Requirements

  • Must be publicly accessible (no authentication required)
  • Must return a valid image file
  • Must respond within 15 seconds
  • HTTPS recommended for security

Aspect Ratios

Templates expect specific aspect ratios. The API will:

  • Crop artwork that doesn't match the template ratio
  • Center the artwork within the frame
  • Preserve the artwork's quality

Common ratios:

  • Portrait: 2:3 (e.g., 2000x3000)
  • Square: 1:1 (e.g., 2000x2000)
  • Landscape: 3:2 (e.g., 3000x2000)

Check the template preview to see the expected ratio.

Performance

Generation Time

Typical render times:

  • Simple templates: 1 to 2 seconds
  • Complex templates: 2 to 4 seconds
  • High resolution (4000px): 3 to 5 seconds

Optimization Tips

  1. Use CDN URLs for artwork to reduce download time
  2. Resize artwork first to match the template ratio
  3. Use JPEG for photos (smaller files than PNG)
  4. Cache mockups if generating the same artwork repeatedly
  5. Batch requests if generating many mockups

Webhooks

Webhooks are not currently supported. All mockups are generated synchronously: the API waits for rendering to complete before responding.

For operations that take a while, consider:

  • Polling: Make requests from a background job queue
  • Timeouts: Set a timeout of 30 seconds on requests
  • Retries: Retry failed requests with exponential backoff

Next Steps