Digital Asset Transformations and Delivery API
- Olivier Grenet
- Patrick Schulz
- Thierry Martinez
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
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.
Wedia DAM Transformation API Documentation
Overview
The Wedia DAM Transformation API enables dynamic image transformations, including format conversion, resizing, cropping, filling, background adjustments, and watermarking. This API facilitates the creation of image derivatives tailored to specific requirements, enhancing both functionality and user experience.
API Endpoint
The primary endpoint for generating image derivatives is the /transform API. It supports various common transformations such as file format conversion, resizing, cropping, and background modifications.
Request Method
GET
HEAD
URL Structure
/api/wedia/dam/transform/{uuid}/{basename}[.suffix]?t=t1&p1=v1&p2=v2&t=t2&p3=v3...
Alternate (legacy) structure
/api/wedia/dam/transform/{type}/{id}/{basename}[.suffix]?t=t1&p1=v1&p2=v2&t=t2&p3=v3...
Path Parameters
uuid: The unique string-encoded identifier for the asset. Recommended for enhanced security.
type: The asset library type (e.g., asset, product_images). Not recommended for public URLs.
id: The unique integer identifier within the asset library.
basename: The desired base name for the output image, useful for SEO purposes.
suffix: (Optional) Specifies the output file format. If omitted or set to .auto, the system selects the best format based on browser capabilities.
Query Parameters
t: Type of transformation (crop, resize, fill, setbg, iwatermark, extend).
p1, p2, p3, …: Parameters specific to each transformation type.
Identifying the DAM Image
To specify which image to transform, use either:
Asset Library and ID: /transform/{type}/{id}/{basename}[.suffix]
Example: /transform/asset/352/ski.jpg
UUID: /transform/{uuid}/{basename}[.suffix]
Example: /transform/d6b81rwf1zejkf8gfi9acwhiuo/ski.jpg
Note: Using UUIDs is strongly recommended to avoid exposing the database structure in public URLs.
Example Using UUID (Recommended):
Example Using Asset Library and ID
Not Recommended as it exposes the underlying structure of the database and can cause a security issue.
Setting the Desired Image Name
You can define an arbitrary name for the output image, which is beneficial for SEO. The basename parameter in the URL sets this name.
Example:
/transform/d6b81rwf1zejkf8gfi9acwhiuo/a-skier-jumping+faction+red+skis.jpg
This returns a JPEG file named a-skier-jumping+faction+red+skis.
Setting the Desired File Format
The file extension in the basename determines the output format. Supported formats include:
.jpg, .jpeg, .jpe
.png
.webp
.heic
.avif
.pdf
Example:
will return an AVIF file
Automatic Format Selection Based on Browser:
If you want to select the best format available for a browser, do not specify the extension :
This will return a .webp file on modern browsers.
Image Transformations
The query string allows chaining multiple transformations. Each transformation is specified by a t parameter followed by its specific parameters.
General Parameter Rules
Numerical Parameters: Can be integers (treated as pixels) or decimals (treated as proportions of the source image).
Integer Example: ?t=resize&width=200&height=200 resizes the image to 200x200 pixels.
Decimal Example: ?t=resize&width=0.5&height=0.5 resizes the image to half its original dimensions.
Supported Transformations
Resize
Crop
Fill
Set Background (setbg)
Image Watermark (iwatermark)
Extend
Resize Transformation
Type: t=resize
Description: Resizes the image without deformation to fit within the specified dimensions.
Parameters:
width or w: Maximum width of the image.
height or h: Maximum height of the image.
Default Behavior: If no parameters are provided, the image retains its original dimensions.
Example:
Crop Transformation
Type: t=crop
Description: Crops the image based on specified parameters. Supports both simple and automatic cropping methods.
a. Simple Crop
Parameters:
x: Horizontal position of the top-left corner of the crop rectangle (can be a proportion).
y: Vertical position of the top-left corner of the crop rectangle (can be a proportion).
width or w: Width of the crop rectangle (can be a proportion).
height or h: Height of the crop rectangle (can be a proportion).
outputWidth: Desired width of the output image in pixels.
outputHeight: Desired height of the output image in pixels.
Example:
b. Automatic Crop Centered on a Focal Point
Parameters:
fx: Horizontal position of the focal point (proportion).
fy: Vertical position of the focal point (proportion).
outputWidth: Desired width of the output image in pixels.
outputHeight: Desired height of the output image in pixels.
Description: Automatically crops the image around the specified focal point to fit the desired aspect ratio, then resizes it to the specified dimensions.
Example:
Fill Transformation
Type: t=fill
Description: Resizes the image to completely fill a specified area. If only one dimension is provided, it behaves like a resize.
Parameters:
width or w: Width of the area to fill.
height or h: Height of the area to fill.
Example:
Set Background (setbg) Transformation
Type: t=setbg
Description: Sets or replaces the background color of an image.
Parameters:
color (required): The desired HTML named color background color (e.g., black, white).
replace: The color to replace (default replaces transparent pixels).
fuzz: Tolerance level for color replacement (default is 1%).
Examples:
Force Tomato Background for a Transparent Source:
Replace White Background with Black:
/api/wedia/dam/transform/asset/12/thumb?t=setbg&color=black&replace=white
Replace White Background with Black with Increased Tolerance:
/api/wedia/dam/transform/asset/12/thumb?t=setbg&color=black&replace=white&fuzz=5%
Image Watermark (iwatermark) Transformation
Type: t=iwatermark (Note the ‘i’ prefix indicating ‘image’)
Description: Adds an image watermark to the asset.
Parameters:
logoType or type: Type of the logo object.
logoId or id: Identifier of the logo.
logoUuid or uuid: (Required if logoType and logoId are not provided) UUID of the logo instance.
logoVariations or variations: (Required) List of logo variations to use for the watermark.
logoMaxWidth or width or w: (Required if logoMaxHeight is not provided) Maximum width of the logo on the image.
Decimal Value: Proportion of the source image (e.g., 0.25 for one-quarter of the source width).
Integer Value: Maximum width in pixels.
logoMaxHeight or height or h: (Required if logoMaxWidth is not provided) Maximum height of the logo on the image.
Decimal Value: Proportion of the source image height.
Integer Value: Maximum height in pixels.
logoGravity or gravity: Placement of the logo on the image (default is center).
Options:
nw (northwest)
n (north)
ne (northeast)
w (west)
c (center)
e (east)
sw (southwest)
s (south)
se (southeast)
logoX or x: X-axis offset relative to the gravity position.
logoY or y: Y-axis offset relative to the gravity position.
Basic Placements:
nw n ne
w c e
sw s se
Example:
/api/wedia/dam/transform/{uuid}/{basename}.jpg?t=iwatermark&logoUuid=abcd1234&logoVariations=main&logoMaxWidth=0.25&logoGravity=se&logoX=10&logoY=10
Extend Transformation
Type: t=extend
Description: Expands the image canvas to fixed dimensions, placing the original asset within it without enlarging the asset. Padding can be added around the asset.
Parameters:
width or w: Final width of the image (default is the source width).
height or h: Final height of the image (default is the source height).
padding: Uniform padding around all sides of the asset.
paddingLeftRight: Minimum padding on the left and right sides (overrides padding for these sides).
paddingTopBottom: Minimum padding on the top and bottom sides (overrides padding for these sides).
paddingColor or color: Color of the padding (default is transparent). Supported colors include standard color names (e.g., red, black, blue).
Example:
/api/wedia/dam/transform/{uuid}/{basename}.jpg?t=extend&width=800&height=600&padding=20&paddingColor=black
Cache Management
The Transformation API utilizes caching to enhance performance. The cache behavior is as follows:
Cache Key Composition: Based on the original asset and the specific transformations applied.
Cache Invalidation:
If the original asset is updated, the cache is automatically invalidated.
Parameter Order and Equivalence:
The order of query parameters does not affect caching.
Equivalent transformation parameters (e.g., ?t=resize&width=0.5&height=0.5 vs. ?t=resize&height=0.50&width=0.50) will utilize the same cached rendition.
Note: Efficient parameter ordering and consistency in transformation specifications can maximize cache utilization.
Security
Access Control: The /transform endpoint applies the objectfile.sendFile security mechanism on the variations used for the transformation. If the security filters out these variations, a 404 Not Found response is returned.
Forwarding: When the endpoint is accessed through a forward, security is not applied directly. Instead, it is delegated to the caller to handle appropriate security measures.
Additional Notes
Asset Libraries: Assets are organized within “asset libraries” (e.g., asset, product_images) established during project initialization.
UUID Generation: The combination of asset library and id is encrypted to generate a unique uuid, ensuring that the database structure remains hidden from external URLs.
REST API Integration: UUIDs are delivered through REST API calls, ensuring seamless integration and secure asset identification.
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)
Using the REST API to get assets and players
Using the REST API, you can query the dam to return a list of media with conditions
Querying the REST API is detailed in the REST API documentation, for the endpoint /api/rest/dam. This endpoint documentation can be obtained via the URL /api/rest/doc/dam, particularly in the documentation section named Asset Collections, which you can directly access via the URL api/rest/doc/dam?tag=assets.
To obtain a list of media, simply call /api/rest/dam/asset, which will return data for all collections.
You can restrict your query to only one collection by using /api/rest/dam/data/<the desired collection>, or only certain collection by indicating the list of collections separated by commas, i.e., /api/rest/dam/data/<list of collections separated by commas>.
The response is a JSON where the $.response.data section lists the different media with:
An identifier (unique per collection) in the id property.
A UUID (unique across the entire solution) in the $uuid property.
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 :
You can get the URLs of the variations and/or players directly, for a specific media, by adding to the end of the URI either the UUID, /api/rest/dam/<uuid>, or the collection and the identifier, /api/rest/dam/<collection>/<id>.
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: */*"To get the list of variation URLs, use the parameter variations=uri, and for the list of player URLs, use the parameter players=uri.
If you don’t know which variations and players are available for this asset, you can retrieve the list of variations in the
variationsproperty and the list of players in theplayersproperty. You can only find the variations and players that exist for the media and to which you have access according to the rights of your connected user.
For example:/api/rest/dam/<a uuid>?variations=uri&players=uriIf you know the name of the variation or player that you need, you can add to the previous parameter respectively the parameter
variation=<name of variation>andplayer=<name of player>to get only that one if it exists and is accessible to you. If you put several names of variations separated by commas, or of players, the first accessible one will be selected from the list.
For example:/api/rest/dam/<a uuid>?variations=uri&variation=<name of variation>&players=uri&player=<name of player>
The variation URLs you will get are in the format:
/api/rest/dam/data/<collection>/<id>/$variation/<name of variation> or /api/rest/dam/data/<uuid>/$variation/<name of variation> for a variation.
/api/rest/dam/data/<collection>/<id>/$player/<name of player> or /api/rest/dam/data/<uuid>/$player/<name of player> for a player.
These are aliases for the dedicated endpoints discussed below.
How to build the URL of a Variation or a Player
You can also directly construct the URL of a variation or a player when you know the collection of the media, the identifier of the media, or the UUID of the media.
Variation
For a variation, use the endpoint :
using the collection + id :
/api/wedia/dam/variation/<collection>/<id>/<name of variation (or list of variations separated by commas)>,
using the uuid :
or /api/wedia/dam/variation/<UUID>/<name of variation (or list of variations separated by commas)>.
Player
For a player, use the endpoint
/api/wedia/dam/player/<name of player (or list of players)>/<collection>/<id>
DAM API Endpoints
These endpoints are aliases of the two mentioned above. However, they must be accompanied by authentication (bearer or x-wedia-api-token cookie). For use in an HTML link or in the src attribute of an img tag, you must use a cookie.
Using the variation url or the player to display the asset in a website
A variation is a binary file, most often an image. To display it, use the appropriate HTML tags depending on the type:
<img>for an image.<object>for a PDF file, for example.<video>for a video.Or even an
<a>tag for a link.
with the SRC pointing to the endpoints retrieved above.
You can specify a filename to enable the downloads
For the /api/wedia/dam/variation endpoint, add the name at the end, for example,
/api/wedia/dam/variation/<uuid>/<name of variation>/<filename>For the /api/rest/dam endpoint, use the filename parameter.
Displaying a Player on a Website
Option 1 : Through the Player API (or the DAM $player endpoint)
The response from the API is directly usable HTML (you can put the URL directly in a browser's address bar).
To display it within an HTML page, use an <iframe> tag, indicating the URL of the desired player in the src attribute. You can add width and height parameters to indicate a size in CSS values.
Option 2 : Direct Integration of Player Code
You can directly integrate the player code within an <iframe> tag via the endpoint /api/wedia/evp/embed.json
Request Parameters:
Either
object: collection
id: identifier of the object
Or
uuid: UUID of the object in the DAM
playerUid (optional): the MediaCloud player to return, the default player will be used if nothing is specified
width (optional): the width in any CSS unit.
height (optional): the height in any CSS unit.
canLogView (optional): true if analytics hits need to be generated
canLogPlaying (optional): true if interactions with the player's buttons should generate analytics hits
You will receive a JSON with different fields: the code to be directly integrated into the iframe tag is found in the IframeCode field.