Assets

Storyblok includes a native digital asset manager (DAM) for asset management and delivery. To upload and manage assets, open the space’s Asset library.

To upload and manage assets programmatically, use the Management API’s assets endpoints.

Note

Learn how to use Storyblok's asset manager in the Assets manual.

Asset CDN

Storyblok delivers all assets via AWS CloudFront CDN. Assets are first served from the origin service, and subsequent calls are cached on the CDN to minimize latency.

Images are served from different domains, depending on the space's region.

Tip

To resolve potential CORS-related limitations, use the a2 domains.

Ensure the project's frontend references the correct domain when handling assets:

Region	URL
United States	https://a-us.storyblok.com, https://a2-us.storyblok.com
Europe	https://a.storyblok.com, https://a2.storyblok.com
Australia	https://a-ap.storyblok.com, https://a2-ap.storyblok.com
Canada	https://a-ca.storyblok.com
China	https://a.storyblokchina.cn

Custom assets domain

To set up a custom domain for assets, follow the tutorial for your cloud service:

Set up a Custom Assets Domain Using Amazon CloudFront

Set up a Custom Assets Domain Using Microsoft Azure

Set up a Custom Assets Domain Using Google Cloud

Image Service

Use Storyblok's Image Service to modify files programmatically: change the file format, optimize the quality, resize, or apply various filters.

Asset MIME types

The asset library supports the following MIME types:

• Image: image/x—png, image/png, image/gif, image/jpeg, image/avif, image/svg+xml, image/webp
• Video: video/*, application/mp4, application/x—mpegurl, application/vnd.apple.mpegurl, audio/webm
• Audio: audio/*
• Text: application/msword, text/plain, application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document

Caution

Spaces without payment info only accept assets with the image/* MIME type.

Unverified spaces accept assets of most MIME types, except text/* and application/*.

Metadata fields

Metadata simplifies asset management and improves the site visitor's experience. Storyblok's DAM includes default fields—namely, alt text, title/caption, copyright, and source. Developers can extend these with custom fields that match the organization's and project's specific needs.

Note

Custom metadata fields and translatable assets metadata may not be available on your plan. Check Storyblok's pricing.

To manage default metadata fields and create custom fields, open Settings → Assets Library. Under Custom metadata fields, name the new field, choose the asset file type, select Add, and Save.

Custom metadata fields support regular expression (regex) validation similar to the standard HTML pattern attribute. Like their default counterparts, custom fields can also be set as Required and Translatable.

Tip

Learn how to work with multiple languages in the Internationalization concept.

Both default and custom metadata fields can be managed programmatically via Storyblok's APIs:

• Content Delivery API: to retrieve an array of assets associated with stories in a space, use the resolve_assets query parameter of the stories endpoint.
• Management API: to retrieve or update metadata fields of assets, use the assets endpoint. The asset object includes a meta_data object that lists all metadata fields of each file, both default and custom ones.

Obtain image dimensions via the API

The example below demonstrates how to extract the width and height of an image from a Storyblok asset URL:

const assetUrl = "//a.storyblok.com/f/51376/664x488/f4f9d1769c/visual-editor-features.webp"
const dimensions = {
  width: assetUrl.split('/')[5].split('x')[0],
  height: assetUrl.split('/')[5].split('x')[1]
}
console.log(dimensions)

This method only works with unmodified images. The asset URL doesn't reflect changes in the following scenarios:

• if a user resized the image using the Image Editor
• if a user replaced the image with a resized version using the Replace Asset app

A more reliable way to track image dimensions is to use the Content Delivery API's stories endpoint. In the request, set resolve_assets=1 to retrieve all assets associated with the story. The response now includes the assets array, where each object contains a  meta_data object with a size key.

"assets": [
    {
      "id": 17075319,
      "content_type": "image/webp",
      "content_length": 6333586,
      "created_at": "2025-08-21T08:17:24.429Z",
      "updated_at": "2025-08-21T08:18:02.522Z",
      "deleted_at": null,
      "alt": "",
      "title": "",
      "copyright": "",
      "focus": "",
      "s3_filename": "f/51376/664x488/f4f9d1769c/visual-editor-features.webp",
      "meta_data": {
        "size": "400x300"
      }
    }
  ]

It may take a few minutes for the size property to apply the updated image dimensions.

Private assets

Mark assets as private to temporarily or permanently hide them from the library and restrict access to these files. Private assets are only accessible via the Content Delivery API with an Asset type access token.

The following example uses the @storyblok/js SDK to retrieve a private asset:

import { apiPlugin, storyblokInit } from '@storyblok/js';

const { storyblokApi } = storyblokInit({
  accessToken: SPACE_TOKEN,
  use: [apiPlugin],
});

const getSignedUrl = async (filename) => {
  const response = await storyblokApi.get('cdn/assets/me', {
    filename: filename,
    token: ASSET_TOKEN,
  });

  return response.data.asset.signed_url;
};

const assetUrl = await getSignedUrl(
'https://a.storyblok.com/f/184738/2560x1946/d20c274998/earth.jpg'
);

document.querySelector('#app').innerHTML = `
  <img src="${assetUrl}" width="200">
`;

Learn how to manipulate private assets using the Image Service.

Related resources

Assets in the Management API