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"
}
]
}
Property | Description |
---|---|
assetId | The ID of the file in Assets Server. |
failureUrl | URL for sending an error message and marking renditions as failed in case of a processing error. |
originalUrl | URL to the original file, used for rendition generation. |
uploadUrl | URL for uploading renditions back to Assets. |
renditionOptions |
List of options describing the requested rendition that needs to be generated. Custom rendition requests will contain the information as requested from the client or API. When a file is uploaded it will request a default preview for which Assets Server will provide a full set of rendition options as configured and a thumbnail request which will contain a format, maxWidth and maxHeight. A list of possible rendition options is listed below. Note: It is the responsibility of the external engine to update the metadata such as assetType/assetDomain of an unknown file type.
Note: This option is not configurable in Assets Server 6.112 and higher. The local watermark value configurable in the cluster-config.properties.txt file will be used.
|
Rendition upload API
POST
|
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.
Example: Assuming the external service rendition name is customName, the name changes as follows:
|
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"'
Name | Type | Description | Example |
---|---|---|---|
assetId | String |
Asset ID of the uploaded rendition. Required. |
AAqYmbINaSI9K8iyaa8Xv- |
rendition | Multipart/form-data |
File with rendition data. Required. |
|
renditionName | String |
Name of the rendition. Same name from the renditionOptions of the processing request. Required. |
maxWidth_1600_maxHeight_1600.jpg |
domain | String |
Asset domain for unknown asset types. Optional. |
image |
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.
File type | Default rendition name |
---|---|
3D | maxWidth_1600_maxHeight_1600.png |
Audio | maxLength_3600000.mp4 |
Document |
preview.pdf maxWidth_1600_maxHeight_1600_page_0.jpg |
Image |
maxWidth_1600_maxHeight_1600.jpg |
AI image |
maxWidth_1600_maxHeight_1600_page_0.jpg |
Layout | maxWidth_1600_maxHeight_1600_page_0.jpg |
maxWidth_1600_maxHeight_1600_page_0.jpg |
|
Presentation |
maxWidth_1600_maxHeight_1600_page_0.jpg preview.pdf |
Text | index.html |
Thumbnail | thumbnail.jpg |
Video | maxWidth_480_maxHeight_360.mp4 |
XML | index.html |
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
POST
|
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
Name | Type | Description | Example |
---|---|---|---|
assetId | String |
Asset ID of the failed rendition. Required. |
AAqYmbINaSI9K8iyaa8Xv- |
preview | Boolean |
Indicates that the default preview generation has failed. Optional |
true |
thumbnail | Boolean |
Indicates that the thumbnail generation has failed. Optional |
true |
message | String |
Error message that is added to the server logs. Required |
'File type ‘PSB’ is not supported.' |
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.
GET
|
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.
GET
|
{
"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.
POST
|
Parameters
Name | Description |
---|---|
body |
Example
|
Updating an engine configuration
Updates an existing engine configuration by referencing its ID.
PUT
|
Parameters
Name | Description |
---|---|
body |
Example
|
Deleting an engine configuration by ID
Deletes an existing engine configuration by referencing its ID.
DELETE
|
Deleting all engine configurations
Deletes all existing engine configurations.
DELETE
|
Revisions
- 17 September 2024: Updated section 'Processing request' by adding a note that the watermark option is not configurable in Assets Server 6.112 and higher.
- 17 September 2024: Updated section 'External engine configuration API' by providing separate examples for Assets Server 6.112 and lower.
Comment
Do you have corrections or additional information about this article? Leave a comment! Do you have a question about what is described in this article? Please contact Support.
0 comments
Please sign in to leave a comment.