The Wedia system can deliver images derivatives at scale through a CDN with a simple API.
You will need to enable the Media Delivery module to gain access to these features, please contact your Wedia account manager to gain access.
Introduction video
https://youtu.be/wKciIMhU8UM
API Endpoints and Swagger documentation
To generate and deliver through Media Delivery an image derivative, you will use the /api/wedia/dam/ API endpoints.
This API has a detailed Swagger documentation that complements this documentation available at :
https://[your DAM server]/api/wedia/dam/?export=swagger
This documentation is not open to public access for security reasons, please contact your Wedia account manager to gain access.
Multiple endpoints are available on this API, the following chapter will describe how to use them to achieve the desired results.
Simple image transformations : format, resize, crop, fill, background
The most common use case for generative image derivatives is to use the /transform API that performs common transformations : file format, resize, crop and background changes.
The API should be called using a GET or HEAD verb.
/api/wedia/transform/{type}/{id}/{basename}[.suffix]?t=t1&p1=v1&p2=v2&t=t2&p3=v3....
or
/api/wedia/transform/{uuid}/{basename}[.suffix]?t=t1&p1=v1&p2=v2&t=t2&p3=v3....
The following sections will explain the API parameters.
Identifying the DAM image that it is called
You need to pass as first arguments values that allow the API to select the image on the DAM you will be transforming.
Typically, DAM objects are stored in a table, with a unique identifier.
Tables are called “asset libraries” in the Wedia DAM. Typical standard asset libraries are “asset”, “product_images”… and this is set up at project initialization.
Ids are autoincrement integers that identify the row in the asset library.
The Wedia system will encrypt the “asset libraries” and “id” combination to generate a unique uuid the avoid exposing the database structure in external facing URLs.
uuid are string encoded, and for example the DAM image on the “asset” asset library with a unique identifier of 224 has a unique uuid of “d6b81rwf1zejkf8gfi9acwhiuo”. Uuids are deliver through REST API calls.
To perform an image transformation on image 352 of the “asset” asset library you can the use either the :
/api/wedia/transform/asset/352/...endpoint, but this is strongly not recommended/api/wedia/transform/d6b81rwf1zejkf8gfi9acwhiuo/...endpoint
We strongly advocate against using asset library / id in public accessible image URLs.
Samples :
Setting the desired image name
You may choose any arbitrary name for you expected image name, that may be useful for SEO purposes.
For exemple : “a-skier-jumping+faction+red+skis” is a totally valid name.
The name is expected in the “basename” value :
api/wedia/transform/d6b81rwf1zejkf8gfi9acwhiuo/a-skier-jumping+faction+red+skis.jpg
will return a file name “a-skier-jumping+faction+red+skis” jpeg file :
Setting the desired file format : jpeg / png / webp …
The file name extension commands the derivate file format : for example, setting a basename of “bicycle.jpg” will output a jpeg file.
Valid extensions are :
.jpg, .jpeg, .jpe
.png
.webp
.heic
.avif
.pdf
Sample :
Selecting the best file format depending on the browser capabilities
Currently, web browsers are well optimized for the webp format, which is quite well supported, but not all browsers support this file format.
The let Wedia DXM automatically select the “best” format, you may either use the “.auto” suffix, or omit the suffix. The system will look into the “accepted” formats of the browser, and if the user browser accepts webp, will return this format, or jpeg if webp is not supported.
Sample :
will return a .webp on modern browsers.
Transforming images for resize, crop, fill, background derivatives
The query string part of the API allows to chain several transformations.
Each transformation starts by identifying the type of the transformation:
t=crop|resize|fill|setbg
Each transformation accepts parameters that are simply passed as :
&name=value.
Numerical parameters can be integer values or decimal values.
Integer values are treated as pixel values.
for example : ?t=resize&width=200&height=200 resizes the source image into a 200x200 pixel square image.
Decimal values represent a proportion of the source:
?t=resize&width=0.5&height=0.5 resizes the source image into a rectangle of half the original dimensions : ( source width / 2 ) x ( source height / 2 ).
Resize transformation
The transformation is called resize: ?t=resize
The image is resized without deformation so that it fits in a rectangle.
The accepted parameters are :
width : maximum width of the image.
height : maximum height of the image.
By default, these two parameters have the corresponding dimension of the source, so ?t=resize means not resizing the source.
Crop transformation and focus point
The transformation is called crop: ?t=crop
Two sets of parameters are accepted for two distinct crop methods.
Simple crop :
x: horizontal position of the top/left corner of the crop rectangle.
y : vertical position of the top/left corner of the crop rectangle.
width : width of the crop rectangle.
height : height of the crop rectangle.
outputwidth: actual width of the output
outputheight: actual height of the output rectangle.
The first 4 parameters define the cutting rectangle. Each of these parameters can be omitted to keep the dimensions of the original image so ?t=crop does not transform the source.
These first 4 parameters can be proportional values (decimal values) because they come from a third party tool (AI extraction or manual cropping tool) and give unwanted rounding of the crop. In this case, it is possible to add the parameters outputWidth and outputHeight in absolute values (integers) to adapt the cropping to the desired size.
Example :
https://club-wed.wedia-group.com/api/wedia/dam/transform/d6b81rwf1zejkf8gfi9acwhiuo/skier?t=crop&x=0.099&y=0.031&width=0.897&height=0.673&outputWidth=500&outputHeight=300
Automatic crop and resize centered on a focal point.
https://youtu.be/xXh0BpBBLUQ
fx : horizontal position of the focal point of the crop rectangle.
fy : vertical position of the focal point of the cropping rectangle.
outputwidth: actual width of the output
outputheight : real height of the output
The principle of this transformation is to make an automatic crop of the image around the focal point in the largest rectangle respecting the ratio outputWidth/outputHeight then resize this cropped image in outputWidth x outputHeight.
Fill
The transformation is called fill: ?t=fill
The accepted parameters are :
width : width of the rectangle to fill.
height : height of the rectangle to fill.
If only one dimension is specified, the behavior is identical to a resize.
Setting the background color for transparent images or uniform backgrounds
The transformation is called setbg: ?t=setbg
The accepted parameters are :
color : ( required ) background color.
replace : color to replace. By default, replace transparent pixels
fuzz : blur of the color replacement. Default : 1%.
Examples
Force black background of a transparent source
/api/wedia/dam/transform/asset/12/thumb?t=setbg&color=black
Replace a white background by a black one
/api/wedia/dam/transform/asset/12/thumb?t=setbg&color=black&replace=white
Replace a white background with a black background with more tolerance on the source color
/api/wedia/dam/transform/asset/12/thumb?t=setbg&color=black&replace=white&fuzz=5%
Cache management
The cache is associated with the starting asset and the actual transformations applied to that asset. This means that :
if the asset changes, the cache is invalidated.
if the order of the parameters changes or their value gives a known transformation, the call takes advantage of the cache : for example,
?t=resize&width=0.5&height=0.5will hit the same cache rendition as?t=resize&height=0.50&width=0.50.
Complex image transformations : watermark, clipping paths, …
In some cases, the image transformations offered by the “transform” endpoint are not sufficient.
For more complexe, chained transformations, we offer a full featured “imaging” API : Imaging : downloading and applying image transformations
Rather than passing the individual transformation in each query string, we advocate the use of image presets.
An image preset is a JSON description of a set of transformations that use the “Imaging” API syntax.
Let’s say we want a “watermark” preset, that resizes, fits in a square, and overlay text on an image.
We can create a “watermark” preset, and use the following API endpoint to serve it :
/api/wedia/dam/variation/{type}/{id}/{variation}/{baseName}
or
/api/wedia/dam/variation/{uuid}/{variation}/{baseName}
The
type, id, uuidparameters are described in the Identifying the DAM image that it is called section of this document.The
basenameis optional, and is described in the Setting the desired image name section of this document
The variation parameter is a single variation name, or a list of different variations, comma separated.
The variations may be built-in the product, or custom : in that case, we will use a “preset” to describe this variation
Using a built-in variation
The Wedia DAM offers standard derivatives, that depend on the media type : image, document, video…
These renditions depend on the original media type :
IMAGES get size depend renditions, and watermarked renditions
VIDEO get resolution renditions, such as SD, HD, 4K, and watermarked renditions
DOCUMENTS (Word, PDF…) get a PDF rendition
INDESIGN files get multiple PDF renditions : PDF low definition, high definition, PDF X3:2002 …
Numerous standard variations exists, the most common are :
thumbnailTiny: an image of 100 pixels height
thumbnailSmall: an image of 200 pixels height
thumbnailBig: an image of 600 pixels height
thumbnailReal : the web rendition of the asset, at its original size (careful with very large Photoshop files !)
thumbnailScreen : a 2000 pixel wide web rendition
poster: the user may contribute a custom thumbnail for some assets, like a cover image. The poster will return that custom thumbnail. Please read the “poster” documentation to learn more about poster management.
default : a placeholder image that represent the image type.
thumbnailSmallAuto : a thumbnail small with transparency with the best format supported by the browser
stripped_background : a variation where the background has bee removed by artificial intelligence.
Another common rendition used is the animated, that will function identically as for thumbnails, but will honor animations from animated GIF and WEBP. In that case, don’t forget to suffix with .gif or .webp to render in a format that supports animations.
animatedReal : the web rendition of the asset, at its original size
animatedScreen : a 2000 pixel wide web rendition
animatedBig : a 600 pixel wide web rendition
animatedSmall : a 200 pixel wide web rendition
ia_preview_video_source : only available for videos, and will return a small mp4 of a “summary” of the video
Developers may create plugins that add derivatives using the Java API : https://club-wed.wedia-group.com/admin/javadoc/res/api/en/user/com/noheto/extensions/interfaces/services/AbstractPresetBusinessService.html
To keep track of all available presets available for a given media, a developer with an active /admin session can use the following API :
/api/wedia/admin/variations/{type}/{id} (please note the “s” in variations)
that will return all available presets for that media, taking into account security rules (see below : Chaining requested variations, and selective watermarking)
[
{
"name": "original",
"description": "original"
},
{
"name": "thumbnailsmall",
"description": "thumbnailsmall"
},
(...)
{
"name": "default",
"description": "thumbnail"
}
]
Creating a custom preset
A variation may be implemented in full Java code, in a plugin, but the easiest way is to use the integration variation editor that accept the JSON syntax described in the Imaging : downloading and applying image transformations documentation.
The editor is available at :
https://server-name/_plugins/WXM_RESTAPI/page/admin/presets/admin.jspz
When creating a new variation, an editor allows to select a name, select an optional output format, and the JSON description of the preset :
Let’s create a preset that will return a square of 300pixels, padded and watermarked jpeg of any image :
Using the thumbnail and watermark commands, can create the following JSON :
{
"thumbnail":{
"height":300,
"width" :300,
"extend": "true"},
"watermark": {
"gravity": "center",
"overlay": "© Wedia",
"font": [
"Liberation-Sans",
"25%",
"bold"
],
"foreground": "#ffffff"
}
}
Using the variation endpoint, the following API call :
https://club-wed.wedia-group.com/api/wedia/dam/variation/d6b81rwf1zejkf8gfi9acwhiuo/watermark
will return this 300x300 watermarked JPEG :
Chaining requested variations, and selective watermarking
It is possible to chain the requested variations :
The system will try to send the leftmost variation first, then the next on its right, until the end of the list.
In our sample, the system will try to send :
a thumbnailbig standard variation (600 pixels height)
then a watermarked preset,
then a generic placeholder of an image.
The use case for chaining variation comes with restrictions on what the user may be allowed to see due to Security Rules.
We can for example set up a security rule that will watermark all assets that have a property of “private” set to 1.
For those assets, the system will evaluate first if the thumbnailbig rendition is allowed : for assets marked as private, the system will return false, and the derivative will not be sent by the API.
The system will then evaluate is the watermarked rendition is allowed : for all assets, this rendition is available, so it will serve the watermarked version.
The security domain for setting such restriction is “Objectfile”, and the action is “SendFile”.
Implementing the example rule would be written :
(LOWER(subTypeOp) = 'watermark') OR (object.private != 1)
Listing all renditions for a media
There are too many renditions to list in this document, and there is an API you can invoke to list all the variations of a given asset :
https://club-wed.wedia-group.com/api/wedia/dam/?export=swagger#/default/get_api_wedia_dam_variations
or if you prefer the REDOC format :
For example, for an “asset” of id “113” :
curl -X GET "https://club-wed.wedia-group.com:443/api/wedia/dam/variations?object=asset&id=113" -H "accept: */*"