Specifying paths for variable images

• Last updated on August 22, 2025
• •
• 1 minute to read

You may have pictures available online. To use online images for variable data printing, provide their public URLs. They must be accessible without any authorization. If an image becomes unavailable (e.g., deleted or inaccessible during rendering), VDP may fail.

As an alternative, you can host public images in your tenant's storage. This is useful when the images do not change from one order to another. For example, you can render logos based on user category, where one logo might be reserved for Silver users and another for Gold users. These image types never change, so you just upload them manually in the file manager, through an API, or after selecting them in a public gallery.

The third option is when these images can change from order to order, for example, photos of a person. Before you begin rendering, you will need to save the images in the same private storage as the template.

Supported image path formats

• A gallery of your artwork that you upload to the Assets > Images section:

  "public:campaign-folder/image.jpg"

• User images that they upload to their private storage:

  "user:campaign-folder/image.jpg"

• Images in an external system can be accessed through their URLs.

  "https://example.com/image.jpg"

Example

The variableData array may look as follows:

"variableData": [
    {
        "name": "Art",
        "type": "Image",
        "value": "public:art/main_artwork.png"
    },
    {
        "name": "Tour images",
        "type": "ImagePlaceholder",
        "value": "user:summer/lake.jpg"
    },
    {
        "name": "Logo",
        "type": "Image",
        "value": "https://example.com/logos/acme-company.svg"
    }
]

The endpoints POST /api/atoms/v1/designs/render-proof and POST /api/atoms/v1/designs/render-preview support these formats. Their request body must include a variableData array with the updated field values.