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.

Requirements

Using this features requires the following versions of Assets Server:

• Assets Server 6.109 or higher: External processing can be used in production.
• Assets Server 6.66 – 6.108: External processing is available in beta stage and should not be used in production.

How it works

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).

If the external service was configured with a custom preview rendition name, then the renditionName should be formed of the same name as added in the service plus the extension extracted from the default rendition name, taken from the table below.

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.

Note: For the files with AI, PDF, HTM and HTML extensions, the preview will always be the original file, unless the multipage preview (for AI and PDF) is used.

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

Example for Assets Server 6.112 and higher:

[    {        "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": "",
       "background": "",
       "cropWidth": -1,
       "cropHeight": -1,
       "cropOffsetX": -1,
       "cropOffsetY": -1,
       "defaultPreview": true
     }],        "assetTypes": [ "tiff", "jpg" ],        "enabled": true,        "returnStorageInfo": true    }
]

Watermark example for Assets Server 6.111 and lower:

{        
  "id": "...",        
  "name": "...",        
  "url": "...",        
  "renditions": [{
    ...,
    "watermarked": true,
    ...
  }],        
  "assetTypes": [...],  
  "enabled": ...,        
  "returnStorageInfo": ...    
}

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