Manage Media / Assets

General

You can add images or documents to the SCAYLE Content Delivery Network (CDN) and assign them to a product in two ways: by uploading files from your local system or by providing URLs of existing images.

These assets can be uploaded as base64 encoded attachments or by specifying the URL of a self-hosted image or document.

Additionally, you can include product asset metadata in the form of simple attributes. Product assets are saved in the provided order and can be updated, along with their attributes, using the respective Admin API endpoint after the product is initially created.

Image attributes, such as angle and type, can enhance the image data displayed in your shop.

Advanced attributes and shop overrides are not supported for assets.

Access your CDN by calling https://{{tenant-space}}.cdn.scayle.cloud.

For example, if your tenant is "acme" and the space is "live," the CDN URL would be: https://acme-live.cdn.scayle.cloud.

Supported Media File Types

The Admin API supports and recommends the following media file types:

JPEG (for high-quality product images)
PNG (for images with transparency)
GIF
PDF

Product Image Entity

Parameter	Details
`id`	Integer READ-ONLY ID assigned by SCAYLE.
`referenceKey`	String A key that uniquely identifies the asset within the tenant's ecosystem.
`name`	String User defined name of the image.
`mimeType`	String READ-ONLY MIME type identified by SCAYLE.
`position`	Integer Specifies the position of the image. Counting starts with 0, so when a product image should be on the first position, you have to send 0.
`source`	AssetSource A source from where to upload an image.
`assetUrl`	String URL of the image, either manually specified or generated by SCAYLE, if the SCAYLE CDN is used.
`attributes`	Attribute A list of attributes attached to the image.

Admin API

When using product images, you can either self host the files or upload them to the SCAYLE CDN. By default, all images are added to the last position of all images. However, you can change the order.

An existing product is a precondition for adding a product image.

Upload images

This method can be used to create a new product image by either specifying a asset source or manually providing the assetUrl.

You either have to provide source or assetUrl depending on your use case. Also, keep in mind that shop-specific overrides are not supported by image attributes.

The productIdentifier is either an id or a referenceKey

let response = await adminApi.apis.Images.createProductImage({productIdentifier: productIdentifier}, {requestBody: newImage});
let createdImage = response.body;

When creating a new product image, you have to decide if you want to upload an image to the SCAYLE CDN or provide the assetUrl manually.

Uploading Images

When uploading an image to the CDN, you have to provide an asset source in the source property of an image. You can either specify an URL or a base64-encoded string containing valid binary image data. We allow URL redirects for uploading images.

Using Self-Hosted Images

If you do not want to upload an image and instead use a self-hosted image, you need to ommit the source property and provide an assetUrl manually.

Position

You can explicitly set the position of a new image. If the order position is specified, the new image will be created at the provided position and all existing images will be moved accordingly. If you do not provide a position, the image will automatically be created at the end of the list.

Parameters

Parameter	Type	Description
`id`	integer	ID assigned by SCAYLE.
`referenceKey`	string	A key that uniquely identifies the asset within the tenant's ecosystem.
`name`	string	User-defined name of the image.
`mimeType`	string	MIME type identified by SCAYLE.
`position`	integer	Specifies the position of the image.
`source`	AssetSource	A source from where to upload an image.
`assetUrl`	string	URL of the image, either manually specified or generated by SCAYLE, if the SCAYLE CDN is used.
`attributes`	Attribute	A list of attributes attached to the image.

Asset Source

Parameter	Type	Description
url	string	URL of remote asset.
attachment	string	Base64-encoded binary asset data.

Upload an Image from a Source URL

let newImage = {
  source: {
    url: "https://example.com/myImage.jpg"
  }
};

let response = await adminApi.apis.Images.createProductImage({productIdentifier: 1}, {requestBody: newImage});
let createdImage = response.body;

Upload an Image from a Local File

let newImage = {
  source: {
    attachment: fs.readFileSync('images/myImage.jpg').toString('base64')
  }
};

let response = await adminApi.apis.Images.createProductImage({productIdentifier: 1}, {requestBody: newImage});
let createdImage = response.body;

Upload a Self-Hosted Image

let newImage = {
  assetUrl: 'images/myImage.jpg'
};

let response = await adminApi.apis.Images.createProductImage({productIdentifier: 1}, {requestBody: newImage});
let createdImage = response.body;

Update product image position

By default, product images are added to the bottom of the image order. However, you can define a specific position for product images.

This method can be used to update the position of a product image. The product image will be moved to the defined position and all other images will be moved accordingly.

let response = await adminApi.apis.Images.patchProductImage(
  {productIdentifier: productIdentifier, imageIdentifier: imageIdentifier},
  {requestBody: image}
);

let updatedImage = response.body;

Parameters

Parameter	Type	Description
`position`	integer	Position of the image.

let image = {
  position: 3
};

let response = await adminApi.apis.Images.patchProductImage(
  {productIdentifier: "product-key", imageIdentifier: "image-key"},
  {requestBody: image}
);

let updatedImage = response.body;

Get image collections

You can request several product images by using the respective unique identifiers (ID or reference key).

This method can be used to get a collection of existing product images.

This method allows you to include nested resources using the with parameter.

let response = await adminApi.apis.Images.getProductImages({productIdentifier: productIdentifier});
let images = response.body.entities;

Options

Parameter	Type	Description
`with`	string	Allows you to load the following nested resources within this request: - attributes

Parameter	Type	Description
`entities`	ProductImage[]	A collection of images.

Get a list of Product Images

let response = await adminApi.apis.Images.getProductImages({productIdentifier: 1});
let images = response.body.entities;

images.forEach(
  image => console.log(image.assetUrl)
);

Delete images

Deleting a product image will remove it completely from SCAYLE. If you want to use it again, you need to upload it again or add it with the respective link.

This method can be used to delete an existing product image along with all its dependencies.

This action can not be undone!

adminApi.apis.Images.deleteProductImage({productIdentifier: productIdentifier, imageIdentifier: imageIdentifier});

Delete an Image by ID

adminApi.apis.Images.deleteProductImage({productIdentifier: 1, imageIdentifier: 1});

Delete an Image by Reference Key

adminApi.apis.Images.deleteProductImage({productIdentifier: "key=product-key", imageIdentifier: "key=image-key"});

Create or Update an Image Attribute

The method is used to create an image attribute if it does not exist or update an existing image attribute.

Shop-specific overrides are not supported by image attributes.

Attribute Locks

To avoid accidentally deleting or updating attributes that were manually added or edited via the SCAYLE, the query parameter ignoreAttributeLocks can be used to control the behaviour of how these updates should be handled.

The default behaviour is to respect attribute locks. Thus, even if an attribute is present in the payload, it will not be updated. The same behaviour will be applied, if an attribute is omitted in the payload, so it will not get deleted.

If you want to force updates or deletion of attributes, you need to set
ignoreAttributeLocks =true . In this case, all attributes get updated or deleted even if they are locked.

Method Signature

let response = await adminApi.apis.Attributes.updateOrCreateProductImageAttribute(
  {productIdentifier: productIdentifier, imageIdentifier: imageIdentifier},
  {requestBody: imageAttribute}
);

let createdImageAttribute = response.body;

Options

The operation can be used with optional parameters - called options:

Parameter Details

Parameter	Details
`ignoreAttributeLocks`	Boolean Force an update of attributes even if they are locked.

ignoreAttributeLocks

Boolean

Force an update of attributes even if they are locked.

Attribute

Parameter	Details
`name`	String The attribute name.
`type`	String The attribute type.
`value`	Array The attribute value where the datatype is defined by the type property.
`isLocked`	Boolean READ-ONLY Specifies if the attribute was locked via SCAYLE Panel.
`shopCountrySpecific`	AttributeShopCountrySpecific Used to override the attribute value for a specific shop country. Only supported by products, product masters and variants.

Create Simple Image Attribute

let attribute = {
  "name": "size",
  "type": "simple",
  "value": "M"
};

let response = await adminApi.apis.Attributes.updateOrCreateProductImageAttribute(
  {productIdentifier: 1, imageIdentifier: 2},
  {requestBody: attribute}
);

let createdAttribute = response.body;

Create a simple list Image Attribute

let attribute = {
  "name": "season",
  "type": "simpleList",
  "value": ["autumn", "winter"]
};

let response = await adminApi.apis.Attributes.updateOrCreateProductImageAttribute(
  {productIdentifier: 1, imageIdentifier: 2},
  {requestBody: attribute}
);

let createdAttribute = response.body;

Create a Localized Image Attribute

let attribute = {
  "name": "collection",
  "type": "localizedString",
  "value": {"de_DE": "einzigartig", "en_GB": "unique"}
};

let response = await adminApi.apis.Attributes.updateOrCreateProductImageAttribute(
  {productIdentifier: 1, imageIdentifier: 2},
  {requestBody: attribute}
);

let createdAttribute = response.body;

Create Localized List Image Attribute

let attribute = {
  "name": "color",
  "type": "localizedStringList",
  "value": [
    {"de_DE": "weiß", "en_GB": "white"},
    {"de_DE": "schwarz", "en_GB": "black"}
  ]
};

let response = await adminApi.apis.Attributes.updateOrCreateProductImageAttribute(
  {productIdentifier: 1, imageIdentifier: 2},
  {requestBody: attribute}
);

let createdAttribute = response.body;

Create Simple Image Attribute ignoring locks

let imageAttribute = {
  "name": "material",
  "type": "simple",
  "value": "cotton"
};

let response = await adminApi.apis.Attributes.updateOrCreateProductImageAttribute(
  {productIdentifier: 1, imageIdentifier: 2, ignoreAttributeLocks: true},
  {requestBody: imageAttribute}
);

let updatedImageAttribute = response.body;

Get an Image Attribute

In SCAYLE, you can request an image attribute of the given group.

The method is used to get an existing image attribute.

Method Signature

let response = await adminApi.apis.Attributes.getProductImageAttribute({
  productIdentifier: productIdentifier,
  imageIdentifier: imageIdentifier,
  attributeGroupName: attributeGroupName
});

let imageAttribute = response.body;

Get an Image Attribute

let response = await adminApi.apis.Attributes.getProductImageAttribute({
  productIdentifier: 1,
  imageIdentifier: 2,
  attributeGroupName: "material"
});

let imageAttribute = response.body;

Get a Collection of Image Attributes

SCAYLE allows you to retrieve all attributes attached to an image.

The method is used to get a collection of existing image attributes.

Method Signature

let response = await adminApi.apis.Attributes.getProductImageAttributes({
  productIdentifier: productIdentifier,
  imageIdentifier: imageIdentifier,
});

let imageAttributes = response.body.entities;

Attribute Collection

Parameter	Details
entities	Attribute A collection of attributes.

Parameter

Details

entities

Attribute

A collection of attributes.

Get a list of Image Attributes

let response = await adminApi.apis.Attributes.getProductImageAttributes({productIdentifier: 1, imageIdentifier: 2});
let imageAttributes = response.body.entities;

Delete an Image Attribute

When deleting images, we distinguish between regular attribute groups and locked attribute groups.
The method is used to delete an image attribute.

Method Signature

adminApi.apis.Attributes.deleteProductImageAttribute({
  productIdentifier: productIdentifier,
  imageIdentifier: imageIdentifier,
  attributeGroupName: attributeGroupName
});

Options

The operation can be used with optional parameters - called options:

Parameter	Details
ignoreAttributeLocks	Boolean Force attributes deletion even if they are locked.

Parameter

Details

ignoreAttributeLocks

Boolean

Force attributes deletion even if they are locked.

Delete an Image Attribute

adminApi.apis.Attributes.deleteProductImageAttribute({
  productIdentifier: 1,
  imageIdentifier: 2,
  attributeGroupName: "material"
});

Delete an image attribute ignoring locks

adminApi.apis.Attributes.deleteProductImageAttribute({
  productIdentifier: 1,
  imageIdentifier: 2,
  attributeGroupName: "material",
  ignoreAttributeLocks: true
});