Generating previews

Last updated on May 15, 2025
•
3 minutes to read

Some assets, like designs, images, or fonts, may have previews. Previews are generated only once, and information about them is automatically added to the asset metadata. If you update an asset file (for example, modify the design), the preview is invalidated and automatically removed.

Each asset may contain more than one preview. For example, it may be a preview for an admin app or for a storefront, or perhaps a storefront app may require a small thumbnail and a larger preview.

"previews": {
    "<namespace>-<name>": {
        "id": "6064221fe810853799cbf2f3",
        "name": "<name>",
        "namespace": "<namespace>",
        "width": 248,
        "height": 141,
        "url": "<URL>"
    }
}

Here, the <namespace> is a unique application name, for example, online-store, backoffice, mystore, etc. The <name> specifies a preview type (like thumbnail, websized, tiny-icon, etc.).

To make Customer's Canvas generate a preview, you need to use the Asset Processor API. It has the endpoint GET /api/processor/v1/designs/{id}/preview/{namespace}/{name}/{width}x{height}, where you can specify the namespace, name, width, height, and some other parameters, and then it will generate the preview and update the metadata.

curl -X \
  GET "https://api.customerscanvashub.com/api/processor/v1/designs/617a4fdd1079e200f24ffeb2/preview/mystore/thumbnail/160x120" \
  -H  "accept: application/octet-stream" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/processor/v1/designs/617a4fdd1079e200f24ffeb2/preview/mystore/thumbnail/160x120

var designId = "64df0541bc24c7f470b3c286"; // Put your real design ID here
var previewNamespace = "mystore"; // Put your real preview name space here
var previewName = "thumbnail"; // Put your real preview name here
var width = 160; // Put your real preview width here
var height = 120; // Put your real preview height here
var response = await designProcessorApiClient.PreparePreviewAsync(designId, previewNamespace, previewName, width, height);
var stream= await response.Content.ReadAsStreamAsync();

var designId = "64df0541bc24c7f470b3c286"; // Put your real design ID here
var previewNamespace = "mystore"; // Put your real preview name space here
var previewName = "thumbnail"; // Put your real preview name here
var width = 160; // Put your real preview width here
var height = 120; // Put your real preview height here
var response = await _designProcessorApiClient.PreparePreview(designId, previewNamespace, previewName, width, height);

$designId = "64df0541bc24c7f470b3c286"; // Put your real design ID here
$previewNamespace = "mystore"; // Put your real preview name space here
$previewName = "thumbnail"; // Put your real preview name here
$width = 160; // Put your real preview width here
$height = 120; // Put your real preview height here
$response = $designProcessorApiClient->designProcessorPreparePreview($designId, $previewNamespace, $previewName, $width, $height);

You don't have to re-request a design element after that. This endpoint returns a preview as a stream that can be sent to a browser right away. Also, there is a version of this endpoint that returns the result as a URL: GET /api/processor/v1/designs/{id}/preview/{namespace}/{name}/{width}x{height}/url.

This way, the workflow is the following:

Request a design entry.
Check whether the metadata.preview["<your_namespace>-<preview_name>"] is not empty.
If you find the preview information, read its url property and insert the acquired URL into the <img> tag.
Otherwise, send a request to Asset Processor and use its output instead of the URL extracted from metadata. Customer's Canvas will automatically add preview information to the design metadata, and it will be recognized the next time Step 2 is performed.

Further Reading

Explore how to create new designs using this API.
Learn how to import already created designs to storage.
Dive into Asset Processor API reference.

Generating previews

Was this page helpful?