# Render Collection API

## POST /renders/bulk

> Create Bulk Renders Based on Mockup Collection

```json
{"openapi":"3.0.3","info":{"title":"Product API Suite","version":"1.0.0"},"servers":[{"url":"https://app.dynamicmockups.com/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key"}}},"paths":{"/renders/bulk":{"post":{"summary":"Create Bulk Renders Based on Mockup Collection","tags":["Bulk Renders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["collection_uuid"],"properties":{"collection_uuid":{"type":"string","format":"uuid","description":"The unique identifier of collection created in My Templates section: https://app.dynamicmockups.com/my-templates\n"},"artworks":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"colors":{"type":"object","description":"Key-value map of color inputs using hex codes"},"export_label":{"type":"string"},"export_options":{"type":"object","description":"Optional settings used to control the format, size, and behavior of the exported images.","properties":{"image_format":{"type":"string","enum":["webp","jpg","png"]},"image_size":{"type":"integer"},"mode":{"type":"string","enum":["view","download"]}}}}}}}},"responses":{"200":{"description":"Successful response of bulk mockup renders","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"export_label":{"type":"string"},"exports":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"label":{"type":"string"}}}}}}}}}}},"400":{"description":"Bad request due to invalid input parameters"},"401":{"description":"Unauthorized request, invalid or missing API key"},"403":{"description":"Insufficient credits to perform this action"},"422":{"description":"Missing required input parameters"}}}}}}
```

### **How to get the collection\_uuid parameter?**

Before you begin, ensure that you have at least one collection created within the  [**My Templates**](https://app.dynamicmockups.com/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.

<figure><img src="https://1410134351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXeuL34FauPTZ6yb0wAep%2Fuploads%2FsakcavOWpAoIZm1d48Po%2Fimage.png?alt=media&#x26;token=ec09ab83-2df7-45ec-9b7a-8c8172c92c5f" alt=""><figcaption><p><strong>Create New Collection</strong></p></figcaption></figure>

To use a template collection in API requests, you will need its unique identifier — `collection_uuid`&#x20;

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.

<figure><img src="https://1410134351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXeuL34FauPTZ6yb0wAep%2Fuploads%2FYwrvDICbsW4coDG0ypqn%2Fimage.png?alt=media&#x26;token=861af9b9-9b3c-410f-bc0b-0319334bb594" alt=""><figcaption><p><strong>Obtain Collection UUID</strong></p></figcaption></figure>

#### 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.

<figure><img src="https://1410134351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXeuL34FauPTZ6yb0wAep%2Fuploads%2FTm2z7WKIw2AxQXehta0d%2Fimage.png?alt=media&#x26;token=1a07b1ed-f554-4ef6-b43e-dde6fd458b74" alt=""><figcaption><p><strong>Open Collection Input Mapping</strong></p></figcaption></figure>

<figure><img src="https://1410134351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXeuL34FauPTZ6yb0wAep%2Fuploads%2F07GwBP0vOdxHg0iEDBDx%2Fimage.png?alt=media&#x26;token=c917dd7c-8fca-4cae-be1a-3402ed067473" alt=""><figcaption><p><strong>Create Collection Input Node</strong></p></figcaption></figure>

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.

<figure><img src="https://1410134351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXeuL34FauPTZ6yb0wAep%2Fuploads%2FY8V7axC5oiaHase0kGq0%2Fimage.png?alt=media&#x26;token=ecd38e67-7cc5-42c6-a2f2-2892d67073cb" alt=""><figcaption><p><strong>Link Inputs Nodes to Collection Mockup Templates</strong></p></figcaption></figure>

### 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:

```json
{
    "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:

```json
{
    "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
    }
}
```

{% hint style="warning" %}
The number of artworks could potentially slow the rendering performance. The fewer artworks used, the faster the response.
{% endhint %}

#### 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:

```json
"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`&#x20;

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:

```json
{
    "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"`.