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

Parameters

Required Parameters

Note: Use either artwork_url (single-frame) OR artwork_urls (multi-frame), not both.

Optional Parameters

Multi-Frame Parameters

For templates with multiple frames (diptych, triptych):

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-Credits-Used: 1
X-Credits-Remaining: 99

Body: Image binary data

JSON Response (response_format=json)

{
  "success": true,
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "width": 2000,
  "height": 1500,
  "format": "jpeg",
  "credits_used": 1,
  "credits_remaining": 99
}

Error Responses

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

400 Bad Request

Invalid request parameters.

{
  "error": "template_id 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",
  "code": "TEMPLATE_NOT_FOUND",
  "details": {
    "template_id": "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"
}

429 Too Many Requests

Rate limit exceeded.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 100,
    "window": "60s",
    "retry_after": 23
  }
}

500 Internal Server Error

Server error during rendering.

{
  "error": "Failed to render mockup",
  "code": "RENDER_ERROR",
  "details": {
    "message": "Template rendering failed"
  }
}

See Error Handling for complete error code reference.

Examples

Basic Mockup

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

High-Quality PNG

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

Multi-Frame Mockup

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

JSON Response

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

Response:

{
  "success": true,
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "width": 2000,
  "height": 1500,
  "format": "jpeg",
  "credits_used": 1,
  "credits_remaining": 99
}

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: 2000px or larger for best quality
• Maximum: 10000px (images are resized if larger)

Artwork URL Requirements

• Must be publicly accessible (no authentication required)
• Must return a valid image file
• Must respond within 10 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-2 seconds
• Complex templates: 2-4 seconds
• High-resolution (4000px): 3-5 seconds

Optimization Tips

1. Use CDN URLs for artwork to reduce download time
2. Pre-size artwork to match 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 long-running operations, consider:

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

Next Steps

• Browse available templates
• Handle errors gracefully
• Understand billing & credits