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
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
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 setignoreAttributeLocks =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 |
---|---|
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. |
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. |
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
});