docs
  1. SCAYLE Resource Center
  2. Developer Guides
  3. Products
  4. Manage Media / Assets

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

ParameterDetails
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

ParameterTypeDescription
idintegerID assigned by SCAYLE.
referenceKeystringA key that uniquely identifies the asset within the tenant's ecosystem.
namestringUser-defined name of the image.
mimeTypestringMIME type identified by SCAYLE.
positionintegerSpecifies the position of the image.
sourceAssetSourceA source from where to upload an image.
assetUrlstringURL of the image, either manually specified or generated by SCAYLE, if the SCAYLE CDN is used.
attributesAttributeA list of attributes attached to the image.

Asset Source

ParameterTypeDescription
urlstringURL of remote asset.
attachmentstringBase64-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

ParameterTypeDescription
positionintegerPosition 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

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

ParameterTypeDescription
withstringAllows you to load the following nested resources within this request: - attributes
ParameterTypeDescription
entitiesProductImage[]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:

ParameterDetails
ignoreAttributeLocks

Boolean

Force an update of attributes even if they are locked.

Attribute

ParameterDetails
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

ParameterDetails
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:

ParameterDetails
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
});