Skip to main content

Dynamic Mockups API: Complete Guide

Learn your way around our powerful Mockups API - fastest and most reliable API on the market.

Written by Dynamic Mockups Support
Updated over 2 months ago

Overview

The Dynamic Mockups API is a RESTful API that enables developers to generate professional product mockups programmatically at scale.

Built on AWS infrastructure for 99.9% reliability, the API processes mockups in under 1 second and integrates seamlessly into any workflow, from e-commerce platforms to custom applications.

Perfect for:

  • Developers building automated mockup workflows

  • E-commerce platforms requiring dynamic product images

  • Print-on-demand businesses automating fulfillment

  • SaaS applications adding mockup generation features

  • Agencies managing client mockups at scale

Base URL: https://app.dynamicmockups.com/api/v1

Documentation: docs.dynamicmockups.com

Looking for the easiest way to test our API for complex POD use cases?
​

Check out our API Playground: playground.dynamicmockups.com

Quick Start: Your First Render in 1 Minute

Try with Sandbox Credentials

We've prepared a ready-to-use request with sandbox credentials so you can test the API immediately:

Endpoint: POST https://app.dynamicmockups.com/api/v1/renders

Headers:

Content-Type: application/json
Accept: application/json
x-api-key: bdf8301a-ef40-457d-8f2e-0d91e18726a0:d1c144ad6cbe665f680584d9a917a2a56c2ae07bd9ddc102cdd881604a159691

Request Body:

{
  "mockup_uuid": "9ffb48c2-264f-42b9-ab86-858c410422cc",
  "smart_objects": [
    {
      "uuid": "cc864498-b8d1-495a-9968-45937edf42b3",
      "asset": {
        "url": "https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png"
      }
    }
  ]
}

Code Examples

curl -X POST https://app.dynamicmockups.com/api/v1/renders \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "x-api-key: bdf8301a-ef40-457d-8f2e-0d91e18726a0:d1c144ad6cbe665f680584d9a917a2a56c2ae07bd9ddc102cdd881604a159691" \
-d '{
  "mockup_uuid": "9ffb48c2-264f-42b9-ab86-858c410422cc",
  "smart_objects": [
    {
      "uuid": "cc864498-b8d1-495a-9968-45937edf42b3",
      "asset": {
        "url": "https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png"
      }
    }
  ]
}'

Node.js

const axios = require('axios');

const url = 'https://app.dynamicmockups.com/api/v1/renders';
const apiKey = 'bdf8301a-ef40-457d-8f2e-0d91e18726a0:d1c144ad6cbe665f680584d9a917a2a56c2ae07bd9ddc102cdd881604a159691';

const data = {
  mockup_uuid: '9ffb48c2-264f-42b9-ab86-858c410422cc',
  smart_objects: [
    {
      uuid: 'cc864498-b8d1-495a-9968-45937edf42b3',
      asset: {
        url: 'https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png'
      }
    }
  ]
};

axios.post(url, data, {
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'x-api-key': apiKey
  }
})
.then(response => {
  console.log('Response:', response.data);
})
.catch(error => {
  console.error('Error:', error.response ? error.response.data : error.message);
});

Python

import requests

url = 'https://app.dynamicmockups.com/api/v1/renders'
api_key = 'bdf8301a-ef40-457d-8f2e-0d91e18726a0:d1c144ad6cbe665f680584d9a917a2a56c2ae07bd9ddc102cdd881604a159691'

data = {
    "mockup_uuid": "9ffb48c2-264f-42b9-ab86-858c410422cc",
    "smart_objects": [
        {
            "uuid": "cc864498-b8d1-495a-9968-45937edf42b3",
            "asset": {
                "url": "https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png"
            }
        }
    ]
}

headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'x-api-key': api_key
}

response = requests.post(url, json=data, headers=headers)

if response.status_code == 200:
    print('Response:', response.json())
else:
    print('Error:', response.status_code, response.text)

JavaScript (Fetch)

const url = 'https://app.dynamicmockups.com/api/v1/renders';
const apiKey = 'bdf8301a-ef40-457d-8f2e-0d91e18726a0:d1c144ad6cbe665f680584d9a917a2a56c2ae07bd9ddc102cdd881604a159691';

const data = {
  mockup_uuid: '9ffb48c2-264f-42b9-ab86-858c410422cc',
  smart_objects: [
    {
      uuid: 'cc864498-b8d1-495a-9968-45937edf42b3',
      asset: {
        url: 'https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png'
      }
    }
  ]
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'x-api-key': apiKey
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => {
  console.log('Response:', data);
})
.catch(error => {
  console.error('Error:', error);
});

PHP

<?php

$url = 'https://app.dynamicmockups.com/api/v1/renders';
$apiKey = 'bdf8301a-ef40-457d-8f2e-0d91e18726a0:d1c144ad6cbe665f680584d9a917a2a56c2ae07bd9ddc102cdd881604a159691';

$data = [
    "mockup_uuid" => "9ffb48c2-264f-42b9-ab86-858c410422cc",
    "smart_objects" => [
        [
            "uuid" => "cc864498-b8d1-495a-9968-45937edf42b3",
            "asset" => [
                "url" => "https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png"
            ]
        ]
    ]
];

$headers = [
    'Content-Type: application/json',
    'Accept: application/json',
    'x-api-key: ' . $apiKey
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo 'Response: ' . $response;
}

curl_close($ch);

Getting Started with Your Own Account

Step 1: Create Your Free API Key

  1. Sign up for a free Dynamic Mockups account

  2. Navigate to the API Dashboard

  3. Click "Create new API key"

  4. Copy your API key and keep it secure

You get 50 free credits to start testing the API immediately.

Step 2: Choose Your Mockup Templates

Browse 1,000+ mockup templates in the mockup library or upload your own custom Photoshop files.

Step 3: Get Mockup and Smart Object UUIDs

Option 1: Copy from URL

When viewing a mockup in the web application, the URL contains the mockup UUID and smart object UUIDs you need for API requests.

Option 2: Use Get Mockups API

Call the Get Mockups API to retrieve all available mockups with their UUIDs programmatically:

GET https://app.dynamicmockups.com/api/v1/mockups

Step 4: Start Rendering

Replace the sandbox mockup UUID and smart object UUID in your API requests with your own, and you're ready to generate mockups!

API Playground

Test API requests interactively without writing code using the API Playground at playground.dynamicmockups.com.

The playground provides:

  • Interactive request builder

  • Pre-configured sandbox examples

  • Real-time response previews

  • Code snippet generation in multiple languages

  • No setup required. Start testing immediately

Perfect for exploring API capabilities before implementation.

Core API Endpoints

1. Render Mockup API

Generate a single mockup with your design.

Endpoint: POST /api/v1/renders

Use for:

  • Single mockup generation

  • Real-time mockup creation

  • Custom design placement and styling

Key Features:

  • Smart object targeting for precise design placement

  • Color overlay options

  • Image format and size configuration

  • Print area customization

  • Adjustment layers (brightness, contrast, saturation, etc.)

  • Pattern generation

  • Blending modes support

  • Text layer support (Beta)

Full Documentation →

2. Bulk Render API (Collection-Based)

Generate multiple mockups from a collection in a single request.

Endpoint: POST /api/v1/renders/bulk

Use for:

  • Generating mockups across multiple templates at once

  • Creating color variations automatically

  • Batch processing with consistent artwork

How It Works: Collections group multiple mockup templates together. Define artwork and color mappings once, then generate all mockups in the collection simultaneously.

Benefits:

  • Faster than individual API calls

  • Consistent branding across templates

  • Fewer API requests = lower cost

Full Documentation →

3. Get Mockups API

Retrieve available mockup templates from your account.

Endpoint: GET /api/v1/mockups

Use for:

  • Discovering available mockups and their UUIDs

  • Filtering mockups by collection or catalog

  • Getting smart object details for each mockup

  • Building dynamic mockup selectors in applications

Optional Filters:

  • catalog_uuid - Filter by catalog

  • collection_uuid - Filter by collection

  • all_catalogs - Include mockups from all catalogs

Specific Mockup: GET /api/v1/mockup/{uuid}

Full Documentation →

4. Collections API

Manage collections of mockup templates.

Endpoints:

  • GET /api/v1/collections - List collections

  • POST /api/v1/collections - Create new collection

Use for:

  • Organizing mockups by product type or use case

  • Setting up bulk render workflows

  • Managing template groups for different clients

Full Documentation →

5. Catalogs API

Access and manage mockup catalogs.

Endpoint: GET /api/v1/catalogs

Use for:

  • Retrieving all available catalogs

  • Organizing mockups at the highest level

  • Filtering mockups and collections by catalog

Full Documentation →

6. Photoshop Files API

Upload and manage custom Photoshop templates programmatically.

Endpoints:

  • POST /api/v1/psd/upload - Upload PSD file

  • POST /api/v1/psd/delete - Delete PSD file

Use for:

  • Automating custom template uploads

  • Creating mockup templates from PSDs programmatically

  • Managing template lifecycle via API

Key Features:

  • Automatic mockup template creation

  • Collection assignment during upload

  • Catalog organization

  • Smart object detection

Full Documentation →

7. Render Print Files API

Export production-ready print files for printing.

Endpoint: POST /api/v1/renders/print-files

Use for:

  • Generating high-resolution print files

  • Extracting smart object contents for production

  • Creating files with custom DPI settings

Output Formats:

  • PNG for digital printing

  • PDF for offset printing

  • Vector files for screen printing

Credit Usage: 2 credits per print file exported

Full Documentation →

Authentication

All API requests require authentication using an API key passed in the x-api-key header:

x-api-key: YOUR_API_KEY_HERE

Required Headers:

Content-Type: application/json Accept: application/json x-api-key: YOUR_API_KEY_HERE

Security Notes:

  • Keep your API key secret

  • Never expose API keys in client-side code

  • Regenerate keys if compromised

  • Contact support if you believe your key has been exposed

Understanding Core Concepts

Mockup UUID

Every mockup template has a unique identifier (UUID). This tells the API which mockup template to use for rendering.

How to get it:

  • Copy from web application URL when viewing a mockup

  • Call the Get Mockups API

  • Available in API Playground

Smart Objects

Smart Objects are layers inside mockup templates where designs are placed. Each Smart Object has its own UUID.

Common Smart Objects:

  • Front design area on apparel

  • Back design area

  • Product surface (mugs, phone cases, etc.)

  • Multiple placement areas

Collections

Collections group multiple mockup templates together, allowing batch generation with consistent artwork and color mappings across all templates in the collection.

Billing & Credits

Credit System:

  • 1 rendered mockup = 1 credit

  • Failed API calls (errors) = 0 credits

  • Print file exports = 2 credits each

Plans:

  • Free Plan: 50 credits (includes watermarks)

  • Pro Plan: Credit bundles from 3,600 to 120,000+ per year

  • Top-ups: Additional credits available for purchase

Monitoring Usage:

  • Track remaining credits in your Subscription page

  • View usage in the dashboard sidebar

  • API calls return credit balance in responses

Pricing Details →

Supported Features

Photoshop Feature Support

Fully Supported:

  • Smart Object Layers

  • Multiple Smart Objects (nested not supported)

  • Text Layers (Beta)

  • Adjustment Layers

  • Blending Modes (all standard modes)

  • Layer Effects (shadows, glows, overlays)

  • Masks and Clipping Masks

  • Warp and Transform

File Formats:

  • Design Assets: JPG, JPEG, PNG, WEBP, GIF

  • Template Files: PSD (Adobe Photoshop)

  • Export Formats: JPG, PNG, WEBP, PDF

Complete Feature List →

Use Cases

E-commerce Automation

Automatically generate product images when:

  • New products are added to catalog

  • Designs are uploaded by customers

  • Orders are received with custom designs

Print-on-Demand Fulfillment

Integrate mockup generation into order workflows:

  • Customer uploads design → API generates preview

  • Order placed → API creates production files

  • Fulfillment partner receives print-ready assets

Product Catalog Management

Maintain thousands of product images:

  • Bulk update all products with new designs

  • Generate seasonal variations automatically

  • Create A/B testing variations

SaaS Product Features

Add mockup generation to your platform:

  • Offer product customization to users

  • Generate previews in real-time

  • Provide download or purchase options

Agency Workflows

Manage client mockups at scale:

  • Automate repetitive mockup tasks

  • Generate client presentations programmatically

  • Maintain brand consistency across projects

Advanced Features

Asset Upload Methods

URL-based (Recommended):

"asset": {   "url": "https://example.com/design.png" }

Binary File Upload:

Use FormData for binary uploads:

const formData = new FormData(); formData.append('mockup_uuid', 'your-mockup-uuid'); formData.append('file', fileBlob, 'design.png');

Color Overlays

Apply color to Smart Objects:

"smart_objects": [   {     "uuid": "...",     "asset": {...},     "color": "#FF5733"   } ]

Print Area Configuration

Control design placement:

"print_area": {   "fit": "contain",  // stretch, contain, cover   "position": {     "top": 100,     "left": 100   },   "size": {     "width": 500,     "height": 500   } }

Adjustment Layers

Fine-tune visual appearance:

"adjustment_layers": {   "brightness": 100,   "contrast": 50,   "opacity": 100,   "saturation": 30,   "vibrance": 15,   "blur": 5 }

Export Options

Configure output settings:

"export_options": {   "image_format": "webp",  // jpg, png, webp   "image_size": 1500,      // max dimension   "mode": "view"           // download or view }

Error Handling

Common Error Codes

401 - Missing API Key

{   "message": "Unauthenticated." }

Solution: Include x-api-key header with valid API key

422 - Invalid Mockup UUID

{   "message": "The selected mockup uuid is invalid.",   "errors": {     "mockup_uuid": ["The selected mockup uuid is invalid."]   } }

Solution: Verify mockup UUID exists in your account

422 - Invalid Smart Object UUID

{   "message": "The selected smart object uuid is invalid." }

Solution: Check smart object UUID matches the mockup

400 - Unsupported File Format

{   "success": false,   "message": "Wrong file URL extension provided." }

Solution: Use supported formats: JPG, JPEG, PNG, WEBP, GIF

500 - Server Error

Contact support if encountering persistent server errors.

Troubleshooting Guide →

Best Practices

✅ Always include Accept header - Set Accept: application/json to avoid confusion

✅ Use Get Mockups API - Programmatically discover UUIDs instead of hardcoding

✅ Handle errors gracefully - Implement proper error handling and retry logic

✅ Cache mockup metadata - Store mockup/smart object UUIDs to reduce API calls

✅ Use collections for bulk operations - More efficient than individual renders

✅ Optimize design assets - Use appropriate file sizes to improve render speed

✅ Monitor credit usage - Track consumption to avoid interruptions

✅ Test with sandbox credentials - Use provided sandbox account before production

Developer Resources

Documentation

Code Examples

  • Ready-to-use snippets in Curl, Node.js, Python, JavaScript, PHP

  • Integration tutorials for Make and Zapier

  • Embeddable editor SDK examples

Support

AI-Assisted Development

  • MCP Server: Connect AI assistants like Claude to Dynamic Mockups API

  • MCP Setup Guide

FAQs

Q: Can I use the API for free?
A: Yes! Create a free account and receive 50 credits to test the API. Free plan includes watermarks on renders.

Q: How fast is mockup generation?
A: Typically under 1 second per mockup, depending on template complexity and design asset size.

Q: Can I upload my own Photoshop templates?
A: Yes! Upload custom PSD files through the web app or Photoshop Files API.

Q: What file formats are supported for designs?
A: JPG, JPEG, PNG, WEBP, and GIF for design assets. PSD for template files.

Q: Is there a rate limit?
A: The API runs on AWS infrastructure and can handle high-volume requests efficiently.

Q: Can I send binary files instead of URLs?
A: Yes! Use FormData to upload binary files directly in API requests.

Q: Do failed API calls consume credits?
A: No. Only successful renders consume credits.

Related Articles
What is Dynamic Mockups?
How to Embed the Mockup Editor on Your Website
Bulk Render API: Automate Large Scale Mockup Generation
Troubleshooting Common Issues
Photoshop Integration
Did this answer your question?