Meet us at PRINT 19. Chicago, IL. Oct. 3 - 5.

Dynamic Image API

The Dynamic Image API represents PsdWebService 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 PsdWebService 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 to PsdWebService 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. PsdWebService 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.

PsdWebService implements these features in the following methods:

  • POST api/preview renders a proof image of a PSD template to display it in a browser (in the JPEG or PNG format).
  • POST api/hires 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:

JavaScript
{
    "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:

JavaScript
{
    "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 in your templates to load them into the Design Editor, omit the markers when specifying the keys. 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 PsdWebService, personalization commands, and API reference in the Dynamic Image Tutorial.

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 type="text/javascript" src="https://code.jquery.com/jquery-2.2.0.js">
    </script>

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

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

    var data = {
        template: "badge.psd",
        data: cfg,
        format: "png"
    };

    $.ajax({
        url: "http://localhost:84/api/preview",
        type: "POST",
        contentType: 'application/json; charset=utf-8',
        dataType: 'json',
        data: JSON.stringify(data),
        success: function(d) { 
            console.log(d);
        },
        error: function(d) { 
            console.error(d.responseText);
        }
    });
}
</script>
</head>

<body>
    <h3>The Dynamic Image Sample</h3>
    <input type="button" value="Go" onclick="render()" />
</body>
</html>

See Also

Manual