---
title: "Dynamic Image API"
canonical: https://customerscanvas.com/docs/cc6/dynamic-image-api.htm
archived: true
applies_to:
  - product: "Customer's Canvas On-Premises"
  - product: "Dynamic Image"
    versions: ["0.x (may differ)"]
---

**You’re viewing outdated documentation.** [View the latest Customer’s Canvas On-Premises documentation](https://customerscanvas.com/docs/on-premises/).

# Dynamic Image API

**Applies to:** Customer's Canvas On-Premises; Dynamic Image 0.x (may differ) · **Archived documentation**
 
The Dynamic Image represents a web application that allows you to generate images dynamically from PSD files, where you can replace and modify layers as needed. You can find this API useful, for example, when you are building an e-commerce system and need to generate a lot of product images for different variants (like colors, size, etc.) or you need to personalize designs by replacing texts and images.
 
This is how the Dynamic Image works. First, you create a multilayer PSD file. For example, it may contain a photo in a **Photo** layer, a text string in a **Name** layer, and a rectangle under these layers in a **Background** layer. Then, you want to personalize the photo, text, and the background color in a hard copy. To perform that, you send an HTTP request where you specify the PSD file name and a list of *commands* defining what to do with each of these layers, e.g. insert an image into the **Photo** layer by the direct URL `http://example.com/image.jpg`, set **John Wood** to the **Name** layer, and change the background color to yellow. The Dynamic Image performs these operations, renders the template, and returns a URL to the resulting image or a PDF file.
 
## Features
  
The Dynamic Image API allows you to use the following personalization features:
 
- Hiding design elements.
- Replacing images (both local images and images by direct URLs).
- Replacing text and text style (font, size, and color).
- Inserting images into a smart object.
- Inserting a PSD file into a smart object, and defining custom parameters for this PSD file.
- Selecting a layer from a group with predefined parameters.

The Dynamic Image implements these features in the following methods:
 
- [POST api/rendering/preview↗](https://customerscanvas.com/support/dynamic-image/reference.md#apirenderingpreview) renders a proof image of a PSD template to display it in a browser (in the JPEG or PNG format).
- [POST api/rendering/hires↗](https://customerscanvas.com/support/dynamic-image/reference.md#apirenderinghires) renders a print-ready high-resolution output (a PDF file).
 
## The Rendering of PSD Templates
  
To render templates, you need to pass the name of your PSD template and personalization data to the **preview** and **hires** methods. Additionally, **preview** takes the configuration of the resulting files in the request payload:
 
```
{
    "template": "badge.psd",
    "size": {
        "maxWidth": 600,
        "maxHeight": 800
    },
    "format": "png",
    "data": {
        ...
    }
}
```
 
Here, the **data** object is responsible for the personalization. Layer names in the PSD file are used as property names (keys). The values are objects defining the content and style of design elements to be replaced and rendered on this template. For example, you can specify commands described at the beginning of this topic as follows:
 
```
{
    "data": {
        "Photo": {
            "type": "image",
            "image": "http://example.com/image.jpg",
            "resizeMode": "fill"
        },
        "Name": {
            "type": "text",
            "text": "John Wood"
        },
        "Background": {
            "type": "shape",
            "color": "#eeeb00"  
        }  
    }
}
```
 
As a result, you get a URL that links to high-resolution outputs. The first time you render a template, this service generates a hi-res image, puts this output to the cache, and gives you a link to the cached image. However, on the next requests, you just get the link to the cached image.
 
Layers included in layer groups are also supported. In this case, specify property names as **"GroupName\\LayerName"**. When you use [markers](https://customerscanvas.com/docs/cc6/supported-markers.htm.md) in your templates to load them into the Design Editor, omit the markers when specifying the keys in **data**. For example, refer to the **Layer Name<LC><VPN>** layer as **Layer Name**.
 
## The Personalization of Design Elements
  
Every command in the **data** object has a type and other settings specifying how to personalize the corresponding layer. In the previous example, we personalized the **image**, **text**, and **shape** layer types. The Dynamic Image API allows you to use commands of the following types:
 
- **text** - to personalize text layers. This type is only applicable to text.
- **image** - to replace images in templates. You can apply this type to image layers and smart objects.
- **shape** - to change colors of vector graphics. This type is only applicable to shapes.
- **switch** - to select a design element from a number of options. In Photoshop, you can arrange these options in a layer group, and then specify the name of the layer that you want to enable in the request. In turn, you can also personalize such a layer by passing the commands. This type is only applicable to layer groups.
- **psd** - to insert another PSD template into a smart object. This can be useful to generate mockup previews. You can only apply this type to smart objects.
- **table** - to generate a table based on a prototype in a smart object. You can apply this type to smart objects that contain a table prototype.

You can find more details about the deployment of the Dynamic Image, personalization commands, and API reference in the [Dynamic Image Tutorial↗](https://customerscanvas.com/support/dynamic-image).
 
## The Sample
  
In this sample, we define the text, image, and background color for the source template and render a proof image. The link to the resulting PNG file appears in the console.
 
```html
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>The Dynamic Image Sample</title>

<script language="javascript">
const render = function() {

    // Personalization data.
    const cfg = {
        "Photo": {
            "type": "image",
            "image": "http://example.com/image.jpg",
            "resizeMode": "fill"
        },
        "Name": {
            "type": "text",
            "text": "John Wood"
        },
        "Background": {
            "type": "shape",
            "color": "#eeeb00"  
        }  
    };

    // The request payload.
    const data = {
        template: "badge.psd",
        data: cfg,
        format: "png"
    };

    (async() => {
        const response = await fetch("http://localhost:84/api/rendering/preview", {
            method: "POST",
            headers: { "Content-Type": "application/json; charset=utf-8" },
            body: JSON.stringify(data)
        });
        const result = await response.json();
        if (response.status === 200)
            // A link to the personalized copy.
            console.log("Personalized image: " + result);
        else if (response.status === 500)
            // Exception details.
            console.log(result.details);
    })()
}
</script>
</head>

<body>
    <h3>The Dynamic Image Sample</h3>
    <input type="button" value="Go" onclick="render()" />
</body>
</html>
```
 
## See Also
  
### Manual
 
- [Getting started with the Dynamic Image](https://customerscanvas.com/docs/cc6/getting-started-with-di.htm.md)
- [Dynamic Image API Reference↗](https://customerscanvas.com/support/dynamic-image)