---
title: "Getting started with Dynamic Image | Customer's Canvas On-Premises"
canonical: "https://customerscanvas.com/docs/on-premises/dynamic-image/getting-started/"
---

# Getting started with Dynamic Image

> Imagine that you are building an e-commerce store that sells personalized mugs. End-users will be able to choose a design of a product or even customize it. Besides that, your store will offer mugs with C-shaped handles of different colors, that can also be personalized. During this tutorial, we'll build a code example that creates a preview image of these mugs.

![The final result](images/mockup-personalized.png)

## Prerequisites

Before we start building the code, you'll need: 

1. A [PSD mockup](#preparing-a-psd-mockup) upon which we'll apply the image;
2. A [design file](#preparing-a-design-file) that will be drawn on this mockup;
3. An account with Customer's Canvas and a [Dynamic Image URL](#dynamic-image-url). If you don't have one yet, contact our [support team](https://customerscanvas.com/account/cases/add). 

### Preparing a PSD mockup

You can use the PSD mockup file that we've prepared for this tutorial. Click [here](pathname:///files/preview-mockup-mug-left.psd) to download it. You can also follow the recommendations in the [PSD Files](https://customerscanvas.com/docs/on-premises/dynamic-image/concepts/psd-files.md) topic to create one by yourself. To render mockups, they must be uploaded to the asset storage.

After you have logged into your Customer's Canvas instance, in the main menu, click **Images** > **New** > **Import**. Then, select your PSD file (for example, **preview-mockup-mug-left.psd**) and click **Open**.

![Import designs to BackOffice](images/import-designs.png)

### Preparing a design file

During this tutorial, we'll render the mockup with a custom design on it. We'll take this design using a URL that should return an image in the JPEG or PNG format. You can place a static file at this URL or a service that generates images. For the purposes of our tutorial, we'll use the image from the [Picsum.Photos](https://picsum.photos/) service, but it's also possible to use your image. 

### Dynamic Image URL 

To make requests to the Dynamic Image API, you need to obtain the URL of the Application. The Dynamic Image URL looks as follows:

`https://cc-apps.aurigma.net/{tenantId}/dynamic-image/{version}`

If you're not sure of your `tenantId` or `version`, you can contact our [support team](https://customerscanvas.com/account/cases/add).

## How the Dynamic Image works

Getting a product preview in the Dynamic Image is a quite simple task. You only need to make an HTTP request to the [Rendering](https://customerscanvas.com/docs/on-premises/dynamic-image/api.md#tag/rendering) endpoint. In the request payload, you must pass at least a PSD image ID and the type of the output image. Also, you may want to apply personalization data to this file.

The easiest way to determine an image ID is to find it in the **Images** section, right-click its thumbnail, click **Properties**, and copy the ID.

![Asset info](images/file-id.png)

As an alternative, you may specify a full path to the image in Asset Storage, including the slash in the beginning, e.g. **/folder/my-mockup.psd**.

:::tip
In some scenarios, it is more convenient to use the ID but it may be better to use full names in other situations. The benefit of using IDs is that even if you move a PSD file between folders, the ID won't change. On the other hand, full names allow loading PSD files based on some naming conventions, for example, if you want to use a product SKU as a mockup name.
:::

:::note
When using a stand-alone application not included in BackOffice, you can specify a relative path to the template, which will be combined with the path specified in the [`TemplatePath`](https://customerscanvas.com/docs/on-premises/dynamic-image/config-backend.md) parameter in **AppSettings.config**. For example, if `TemplatePath` is `"c:\inetpub\mockups"`, then specifying the **/folder/my-mockup.psd** template, Dynamic Image will refer to **c:\inetpub\mockups\folder\my-mockup.psd**.
:::

### The minimal possible rendering request

Here, you can see the minimal request that creates the PSD preview without any changes.  

```json
POST https://<your-dynamic-image-instance>/api/rendering/preview
{
    'template': '/mugs/preview-mockup-mug-left.psd',
    'format': 'png'
}
```

It will return a URL to a rendered image, similar to this one:

`https://<your-dynamic-image-instance>/api/download/?file=6191D97FD6D484C220755B53333598B8.png`

![Preview mockup](images/static-mockup.png)

### Change the Shape layer color

Now, let's try to change the handle color. To do this, add a `data` object to the request. The keys of this object are the layer names, while the values are the _commands_ of different types. 

:::tip
* If your PSD file contains groups, you may access the items in a group by adding its name to a key separated by a double backslash, like **GroupName\\\\LayerName**.
* Layers included in Smart Objects are also supported. If a Smart Object contains ungrouped layers, you can personalize a single layer through **"SmartObjectName\\\\LayerName"**. You can also replace the whole Smart Object by specifying property names as **"SmartObjectName"**.
:::

Each command is an object containing a `type` property such as `shape`, `image`, `psd`, `switch`, etc. and additional properties containing your personalization data. For example, to recolor a Shape Layer named **Handle**, you should send a `shape` command and send over its `color`, as follows: 

```json
POST https://<your-dynamic-image-instance>/api/rendering/preview
{
    "template": "/mugs/preview-mockup-mug-left.psd",
    "format": "png",
    "data": {
        "Handle": {
            "type": "shape",
            "color": "#686343"
        }
    }
}
```

![Changing colors on preview mockups.](images/shape-color-on-mockup.png)

### Insert an image into a Smart Object

To insert an image from a URL to a Smart Object, or an Image Item called **Design**, you need to send another command - `image` along with this URL:  

```json
POST https://<your-dynamic-image-instance>/api/rendering/preview
{
    "template": "/mugs/preview-mockup-mug-left.psd",
    "format": "png",
    "data": {
        "Handle": {
            "type": "shape",
            "color": "#686343"
        },
        "Design": {
            "type": "image",
            "url": "https://picsum.photos/seed/picsum/1200/400"
        }
    }
}
```

![Replacing a layer on preview mockups.](images/replaced-layer-on-mockup.png)

Now that we've learned the basic principles of the Dynamic Image, let's take a look at the code example. 

## Code example

For brevity, this tutorial contains the code that you can run from the command line. In a web app, you will need to call similar code in a controller.

**Python**

### Python

Copy the following script to a file, for example, **dynamic-image.py**.

```python title="dynamic-image.py"
# Personalized Request
import requests
# Provide a request payload.
payload = {
    'template': '/mugs/preview-mockup-mug-left.psd',
    'format': 'png',
    'data': {
    	'Design\\Left': {
            'type': 'image',
            'image': 'https://picsum.photos/id/425/1200/600',
            'resizeMode': 'fill'
    	},
    	'Handle': {
    		'type': 'shape',
    		'color': '#686343'
    	} 
    }
}
# Make a request.
r = requests.post('https://<your-dynamic-image-instance>/api/rendering/preview', json = payload)
if  r.status_code == 200:
    # Print a link to the personalized preview image.
    print (r.json())
```

Install the [Requests](https://pypi.org/project/requests/) library. To do so, type the following in the command prompt.

```shell
$ pip install requests 
```

Replace the placeholder `<your-dynamic-image-instance>` with the correct Dynamic Image base URL. Then, run the script:

```shell
$ python dynamic-image.py
```

**JavaScript/TypeScript**

### JavaScript/TypeScript

It is supposed that you already have NodeJS installed. If you have not done so yet, install it first.

Copy the following script to a file, for example, **dynamic-image.js**.

```typescript title="dynamic-image.js"
// Personalized Request
import fetch from 'node-fetch';

// Provide a request payload.
const payload = {
    template: '/mugs/preview-mockup-mug-left.psd',
    format: 'png',
    data: {
        'Design\\Left': {
            type: 'image',
            image: 'https://picsum.photos/id/425/1200/600',
            resizeMode: 'fill'
        },
        Handle: {
            type: 'shape',
            color: '#686343'
        } 
    }
};

// Make a request.
const response = await fetch('https://<your-dynamic-image-instance>/api/rendering/preview', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
});

if (response.ok) {
    // Print a link to the personalized preview image.
    const result = await response.json();
    console.log(result);
}
```

Install the [node-fetch](https://pypi.org/project/requests/) library. To do so, type the following in the command prompt.

```shell
$ npm install node-fetch
```

Replace the placeholder `<your-dynamic-image-instance>` with the correct Dynamic Image base URL. Then, run the script:

```shell
$ node dynamic-image.js
```

:::tip
If you have installed the TypeScript and ts-node package, you can also run this example as **dynamic-image.ts** TypeScript file as follows:

`$ ts-node dynamic-image.ts`
:::

**C#**

### C#

Create an empty console application, for example, using this command:

```shell
$ dotnet new console 
```

Replace the **Program.cs** file with the following code:

```csharp title="Program.cs"
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;

class Program
{
    static async Task Main(string[] args)
    {
        // Personalized Request
        // Provide a request payload.
        var payload = new
        {
            template = "/mugs/preview-mockup-mug-left.psd",
            format = "png",
            data = new
            {
                ["Design\\Left"] = new
                {
                    type = "image",
                    image = "https://picsum.photos/id/425/1200/600",
                    resizeMode = "fill"
                },
                Handle = new
                {
                    type = "shape",
                    color = "#686343"
                }
            }
        };

        // Make a request.
        using var client = new HttpClient();
        var content = new StringContent(
            JsonSerializer.Serialize(payload),
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync(
            "https://<your-dynamic-image-instance>/api/rendering/preview",
            content
        );

        if (response.IsSuccessStatusCode)
        {
            // Print a link to the personalized preview image.
            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}
```

Replace the placeholder `<your-dynamic-image-instance>` with the correct Dynamic Image base URL. Then, run the application:

```shell
$ dotnet run
```

**PHP**

### PHP

Copy the following code to a file, for example, **dynamic-image.php**.

```php title="dynamic-image.php"
<?php
// Personalized Request
// Provide a request payload.
$payload = [
    'template' => '/mugs/preview-mockup-mug-left.psd',
    'format' => 'png',
    'data' => [
        'Design\\Left' => [
            'type' => 'image',
            'image' => 'https://picsum.photos/id/425/1200/600',
            'resizeMode' => 'fill'
        ],
        'Handle' => [
            'type' => 'shape',
            'color' => '#686343'
        ]
    ]
];

// Make a request.
$ch = curl_init('https://<your-dynamic-image-instance>/api/rendering/preview');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode == 200) {
    // Print a link to the personalized preview image.
    echo $response;
}
?>
```

Replace the placeholder `<your-dynamic-image-instance>` with the correct Dynamic Image base URL. Then, run the script:

```shell
$ php -f dynamic-image.php
```