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"
}
]
}| 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.
|
Rendition upload API
|
POST |
The Rendition upload API is used for uploading a rendition from an external engine to the Assets Server storage.
Parameters
| 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 |
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 |
[ { "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.
|
GET |
{
"id": "2hmwbFDRaah9xY8UlU5uzy",
"name": "engine 1",
"url": "http://192.168.1.1:5000/api/processing",
"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 |
Comments
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.
2 comments
Admin endpoint is wrong. Correct path is /services/admin/externalProcessing
Hi Sergei,
Thanks for pointing this out, it has been corrected now.
Best regards,
Maarten van Kleinwee
Senior Technical Writer, WoodWing Software
Please sign in to leave a comment.