The Wedia system can deliver images derivatives at scale through a CDN with a simple API.
| Info |
|---|
You will need to enable the Media Delivery module to gain access to these features, please contact your Wedia account manager to gain access. |
| Table of Contents |
|---|
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.
...
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
| Note |
|---|
We strongly advocate against using asset library / id in public accessible image URLs. |
Samples :
https://club-wed.wedia-group.com/api/wedia/dam/transform/asset/352/ski.jpgThe Wedia system can deliver images derivatives at scale through a CDN with a simple API.
| Info |
|---|
You will need to enable the Media Delivery module to gain access to these features, please contact your Wedia account manager to gain access. |
| Table of Contents |
|---|
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
| Warning |
|---|
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
...
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
...
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:
https://club-wed.wedia-group.com/api/wedia/dam/transform/d6b81rwf1zejkf8gfi9acwhiuo/a-skier-jumping+faction+red+skis.jpg.webp?t=resize&width=200300&height=200
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 =300
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:
https://club-wed.wedia-group.com/api/wedia/dam/transform/d6b81rwf1zejkf8gfi9acwhiuo/a-skier-jumping+faction+red+skis.webp?t=resize&width=200&height=200
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.
...
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:
https://club-wed.wedia-group.com/api/wedia/dam/transform/d6b81rwf1zejkf8gfi9acwhiuo/a-skier-jumping+faction+red+skis?t=resize&width=200&height=200
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.
https://club-wed.wedia-group.com/ski.webp?t=crop&fx=0.819&fy=0.430&outputWidth=200&outputHeight=300
...
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/d6b81rwf1zejkf8gfi9acwhiuo/skier.webpasset/12/thumb?t=resize&width=300&height=300
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.
...
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.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
https://club-wed.wedia-group.com/api/wedia/dam/transform/d6b81rwf1zejkf8gfi9acwhiuo/ski.webpjpg?t=crop&fx=0.819&fy=0.430&outputWidth=200&outputHeight=300
...
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 sourceiwatermark&logoUuid=ruwheefedknpfssojzuws6wwcw&logoVariations=thumbnailBig.webp&logoMaxWidth=400&logoGravity=c&logoX=100&logoY=100
...
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/asset/12/thumb{uuid}/{basename}.jpg?t=setbg&colorextend&width=800&height=600&padding=20&paddingColor=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.
...
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, …
...