Render Collection API

Create Bulk Renders Based on Mockup Collection

post

Authorizations

X-Api-KeystringRequired

Body

collection_uuidstring · uuidRequired

The unique identifier of collection created in My Templates section: https://app.dynamicmockups.com/my-templates

Example: 4f21ac10-67ff-42f4-9362-84a7498c8a9b

colorsobjectOptional

Key-value map of color inputs using hex codes

Example: {"color_primary":"#FF5733"}

export_labelstringOptionalExample: fall_collection_render

Responses

200

Successful response of bulk mockup renders

application/json

successbooleanOptionalExample: true

messagestringOptional

400

Bad request due to invalid input parameters

401

Unauthorized request, invalid or missing API key

403

Insufficient credits to perform this action

422

Missing required input parameters

post/renders/bulk

POST /api/v1/renders/bulk HTTP/1.1
Host: app.dynamicmockups.com
X-Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 279

{
  "collection_uuid": "4f21ac10-67ff-42f4-9362-84a7498c8a9b",
  "artworks": {
    "artwork_main": "https://cdn.example.com/artworks/logo.png"
  },
  "colors": {
    "color_primary": "#FF5733"
  },
  "export_label": "fall_collection_render",
  "export_options": {
    "image_format": "webp",
    "image_size": 360,
    "mode": "view"
  }
}

{
  "success": true,
  "message": "",
  "data": {
    "export_label": "fall_collection_render",
    "exports": [
      {
        "url": "https://cdn.example.com/exports/rendered_image_01.webp",
        "label": "Modern-Living-Room-Frame"
      },
      {
        "url": "https://cdn.example.com/exports/rendered_image_02.webp",
        "label": "Bright-Studio-Canvas-Display"
      }
    ]
  }
}

How to get the collection_uuid parameter?

Before you begin, ensure that you have at least one collection created within the My Templates section. The following example demonstrates how to create a new collection using the Dynamic Mockup application:

Note: A collection is required to store and manage your mockup templates for future use of bulk mockup renders.

Create New Collection

To use a template collection in API requests, you will need its unique identifier — collection_uuid

Steps to Obtain the collection_uuid

1. Open the desired template collection in the Dynamic Mockup application.

2. Locate the Collection UUID menu item.

3. Take this value and use it as the collection_uuid parameter in your API request.

Obtain Collection UUID

About Collections

A collection allows you to group multiple mockup template styles for a product. In this way you can generate multiple grouped mockup in one API call. For example, you can define two collections for the same product depanding on your needs:

• Summer photoshoot session

• Winter photoshoot session

By targeting different collection_uuid values, you can easily switch between template collections in each API call.

Collection Mapping Inputs

Each collection can define Artwork and/or Color mapping inputs. This Input Mapping feature allows you to:

• Apply the same artwork or color to multiple mockup templates.

• Ensure consistent customization across different templates in the same collection.

Open Collection Input Mapping

Create Collection Input Node

In the image below, the artwork_main and color_main collection mapping inputs have been added. The artwork specified for artwork_main and the colors specified for color_main will be applied to all associated mockups.

Link Inputs Nodes to Collection Mockup Templates

artworks

Provided artworks can be attached to any mockup template from a targeted collection.

This is what we call collection input mapping.

You can create any number of artwork inputs and attach them to any mockup template from the collection and its smart objects.

For example, defined artwork_main mapping input will be used in the Bulk Render API like this:

{
    "collection_uuid": "0663101b-f01c-4e85-89af-f90b4e9f983b",
    "artworks": {
        "artwork_main": "https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png"
    }
}

You can provide any number of artworks, you can name them as you want. And you can do something like this:

{
    "collection_uuid": "0663101b-f01c-4e85-89af-f90b4e9f983b",
    "artworks": {
        "artwork_main": "https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png",
        "artwork_secondary": "https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png",
        //add any number of artworks needed
    }
}

The number of artworks could potentially slow the rendering performance. The fewer artworks used, the faster the response.

Send artwork as a binary file instead of a URL

In some cases, you will want to send the binary file instead of the URL.

When sending a binary file in an API request, you must use FormData instead of sending the file as part of a JSON payload. This is because binary files cannot be directly represented in JSON format.

In this example, instead of:

"artwork_main": "https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png",

Send a binary file artwork_main using FormData

When sending FormData, you don't need to send all the artworks as binary files; you can send a combination of URLs and binary files if needed.

In the case above, artwork_main could be sent as a binary file, but artwork_secondary can still be sent as a URL.

The image must be one of the following extensions: jpg, jpeg, png, webp, gif

colors

Besides artworks, you can also attach colors.

From the image above, we've added color_main only to the last template in a collection because we want to apply the color only to that template image when getting the rendered images.

The request would look something like this:

{
    "collection_uuid": "0663101b-f01c-4e85-89af-f90b4e9f983b",
    "artworks": {
        "artwork_main": "https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png"
    },
    "colors": {
        "color_main": "#C0375E"
    }
}

As we created our flow while mapping, this color will only be attached to the last template. The first and the second templates will only get the provided artwork_main .

export_label

When defining this optional parameter in your request, the response will return the same value.

This parameter is used to help recognize the request you sent with the label.

export_options.image_format

By default, all the images are returned in PNG format.

But sometimes, for example, you want to get more optimized images for the web.

By providing some of the following values: jpg, png, webp you can control what image format you want from our API.

export_options.image_size

Same as image_format, you can tell our API if you need images of a specific size.

All the images will be returned in high resolution, but sometimes you need smaller ones.

Provide export_options.image_size = 720 to get images with a 720px width.

The provided value will define the image's width. The height will auto-scale.

export_options.mode

Our API exports images as binary by default, causing the browser to download them automatically.

To display the images in the browser instead of downloading it, set export_options.mode = "view".