Assets Server API - External processing

With the External processing API, the generation of previews and thumbnails of images, videos, and audio files can be handed off to an external service, thereby freeing up internal processing power for other tasks.

In addition, external services can be used for generating previews and thumbnails for specific file formats when Assets Server itself cannot generate these files.

How it works

Info: This feature is in beta stage and requires Assets Server 6.66 or higher. It should not be used in production.

An external service is configured in Assets Server with a definition of which file types it can handle. Whenever a thumbnail or preview is required for that file type, Assets Server sends out a processing request to that URL. The external service then downloads the original file, generates a preview and thumbnail, and sends these back to Assets Server.

For files that are uploaded, Assets Server does not wait on the generated files and it may therefore take a while before these are available. When the request is from a client application or a download request of a custom rendition, the request will wait for the generated files to be send over.

Processing request

Assets Server sends the following request to the external processing service for the configured file types:

 {
    "assetId": "AAqYmbINaSI9K8iyaa8Xv-",
    "failureUrl": "http://dam.example.com:8080/api/asset/rendition/failed/AAqYmbINaSI9K8iyaa8Xv-",
    "originalUrl": "http://dam.example.com:8080/file/AAqYmbINaSI9K8iyaa8Xv-/*/3-1.png?_=2",
    "uploadUrl": "http://dam.example.com:8080/api/asset/rendition/AAqYmbINaSI9K8iyaa8Xv-",
    "renditionOptions": [
        {
            "format": "jpg",
            "maxHeight": 1600,
            "maxWidth": 1600,
            "name": "maxWidth_1600_maxHeight_1600.jpg",
            "quality": 75
        },
        {
            "format": "jpg",
            "maxHeight": 256,
            "maxWidth": 256,
            "name": "thumbnail.jpg"
        }
    ]
}

Rendition upload API

http://yourserver.com/api/asset/rendition/<assetId>

http://yourserver.com/api/asset/rendition/BdyVCs2hqzmAynsuIxIyEf

The Rendition upload API is used for uploading a rendition from an external engine to the Assets Server storage.

A rendition can be a thumbnail or a preview. To choose what is uploaded, use the exact renditionName that Assets Server sends in the body of the Processing request. The Processing request that Assets Server sends will contain the name of the preview file (for example: maxWidth_1600_maxHeight_1600.jpg ) and the name of the thumbnail (for example: thumbnail.jpg).

Parameters

Parameters should be written in the Body of the POST request in form-data:

curl --location 'http://yourserver.com/api/asset/rendition/BdyVCs2hqzmAynsuIxIyEf' \
--header 'X-CSRF-TOKEN: <token>' \
--header 'Authorization: Bearer <bearer>' \
--form 'rendition=@"/C:/thumbnail.jpg"' \
--form 'renditionName="thumbnail.jpg"'

Depending on the file type, Assets Server contains the default rendition names as shown in the table below.

These rendition names should be used in the Rendition upload API POST request if a custom one was not set.

Processing failure API

http://yourserver.com/api/asset/rendition/failed/<assetId>

http://yourserver.com/api/asset/rendition/failed/BdyVCs2hqzmAynsuIxIyEf

The Processing failure API is used for reporting processing failures that occurred on the external engine. It sets the rendition state as failed and adds a failure message to the server logs.

Parameters

External engine configuration API

The External engine configuration API is used for managing external engine configurations such as getting its details, adding or removing configurations, and so on.

Referencing a configuration

Returns a list of configured external engines.

http://yourserver.com/services/admin/externalProcessing

[    {        "id": "2hmwbFDRaah9xY8UlU5uzy",        "name": "engine 1",        "url": "http://192.168.1.1:5000/api/processing",        "renditions": [],        "assetTypes": [ "png" ],        "enabled": true,        "returnStorageInfo": true    },
     {        "id": "61h7AsIHKeCBz3JJGwK1P5",        "name": "engine 2",        "url": "http://engine2.com:8080/generate",        "renditions": [{
       "format": "jpg",
       "scale": -1,
       "maxWidth": 1600,
       "maxHeight": 1600,
       "maxLength": -1,
       "ppi": -1,
       "ppiEnabled": false,
       "page": -1,
       "embedMetadata": false,
       "embedColorProfile": false,
       "skipfront": -1,
       "compression": "",
       "quality": -1,
       "resizeMode": "",
       "watermarked": false,
       "background": "",
       "cropWidth": -1,
       "cropHeight": -1,
       "cropOffsetX": -1,
       "cropOffsetY": -1,
       "defaultPreview": true
     }],        "assetTypes": [ "tiff", "jpg" ],        "enabled": true,        "returnStorageInfo": true    }
]

Referencing a configuration with an ID

Returns the configuration of a specific external engine by referencing its ID.

http://yourserver.com/services/admin/externalProcessing/<id>

http://yourserver.com/services/admin/externalProcessing/4AM0ZNQ5qsLAGG9lIJr2_5

{
        "id": "2hmwbFDRaah9xY8UlU5uzy",
        "name": "engine 1",
        "url": "http://yourserver.com/services/admin/externalProcessing/4AM0ZNQ5qsLAGG9lIJr2_5",
        "renditions": [],
        "assetTypes": [
            "png"
        ],
        "enabled": true,
        "returnStorageInfo": true
}

Adding a new external engine configuration

Adds a new external engine configuration.

http://yourserver.com/services/admin/externalProcessing

Parameters

{
        "name": "engine 1",
        "url": "http://yourserver.com/services/admin/externalProcessing",
        "renditions": [],
        "assetTypes": [
            "png"
        ],
        "enabled": true,
        "returnStorageInfo": true
}

Updating an engine configuration

Updates an existing engine configuration by referencing its ID.

http://yourserver.com/services/admin/externalProcessing/<id>

http://yourserver.com/services/admin/externalProcessing/4AM0ZNQ5qsLAGG9lIJr2_5

Parameters

{
        "name": "engine 1",
        "url": "http://yourserver.com/services/admin/externalProcessing/4AM0ZNQ5qsLAGG9lIJr2_5",
        "renditions": [],
        "assetTypes": [
            "png"
        ],
        "enabled": true,
        "returnStorageInfo": false
}

Deleting an engine configuration by ID

Deletes an existing engine configuration by referencing its ID.

http://yourserver.com/services/admin/externalProcessing/<id>

http://yourserver.com/services/admin/externalProcessing/4AM0ZNQ5qsLAGG9lIJr2_5

Deleting all engine configurations

Deletes all existing engine configurations.

http://yourserver.com/services/admin/externalProcessing/all

Revisions

• 16 May 2023: Updated section 'Rendition upload API' with an overview of the default rendition names.
• 26 April 2023: Updated section 'Rendition upload API' with information about the file that should be uploaded.
• 26 April 2023: Added various new POST and GET examples.