Images
Image scaling and distribution
Serve scaled and optimized images from the Richie CDN
Richie offers facilities for caching and serving processed and optimized images, with originals hosted on the web.
The images can be resized, cropped and watermarked, if necessary. The original and resulting images are cached to minimize traffic. The resulting images are optimized for minimum download size, while maintaining a high level of visual quality.
Source images are either fetched from an origin agreed in the setup phase, or alternatively using encrypted URLs requested from a dedicated API endpoint.
Setup and some limitations
To use images endpoints, contact Richie for setup. To start using encrypted URLs, you will receive credentials. To start using clear URLs, you will need to provide an origin URL to which source image URLs are relative.
Fully supported source file formats are GIF, JPEG, PNG, WEBP and BMP. SVG is cached and served without processing.
Output format can be agreed when configuring the service, or it can be set for individual requests.
It is also possible to declare a watermark scheme, which means agreeing to draw other images and rectangles on top of source images. The method for requesting watermarks is different for clear relative and encrypted URLs. When using encrypted URLs, non-tamperable watermarks are requested at encryption time. If it is not necessary to protect watermark from tampering, watermarks can also be requested when requesting the image. When using clear relative URLs, the watermarks are always requested with the image request.
Endpoints
Encryption API
Encrypted image URLs are requested from Encryption API. You will provide clear URLs and whether you want to use non-tamperable watermarks, and Encryption API will return distributable public URLs to the images on Richie CDN. It is also possible to receive feature detection based center points at this phase.
You will need to provide your credentials in HTTP Basic Authorization scheme to use Encryption API.
Input for Encryption API is a JSON document with the following keys. All are optional. Meaningful use will require at least one URL, though.
Non-tamperable watermarks are requested during the encryption phase. If a watermark scheme is requested at the encryption phase, the query parameter wm in the resulting image URL must be included in all image requests. If the parameter is missing or it has been altered, Images API will refuse to serve the image.
Example request document:
{
"include_thumbnail_crop": true,
"urls": [
"https://images.example.com/800x1800.jpg"
],
"watermark_scheme": "logos"
}The current version of image encrypt API returns HTTP 200 on some error conditions, since it is batch based. If an individual image processing finished with errors, the result JSON object has field "errors" with some information about the errors. If none of the results has "errors", all operations finished successfully.
On success, response JSON document will contain encrypted URLs for all the images and possibly crop boxes.
Here's an example:
{
"processedURLs": {
"https://picsum.photos/800/1900?random=1": {
"encrypted_url": "https://data.richie.app/images/v1/TestTenant/lAR0J4vb-8SWaouf3R5zSPKmxmDrZakksuOg2h4RBpRR984D4dx-fjwDMo3Auac?wm=logos",
"properties": {
"height": 800,
"width": 1800
},
"thumbnail_crop": {
"center_x": 0,
"center_y": 0.6
}
}
}
}Here's the format.
{
// processedURLs is always present in the result, success or not. Its result is a JSON object, with source URLs as keys.
"processedURLs": {
<source URL>: {
// In this object, each value may or may not appear.
// If encryption was successful, "encrypted_url" is present.
"encrypted_url": <encrypted URL>,
// If thumbnail crop was requested and recognition was successful, "properties" and "thumbnail_crop" are present.
"properties": {
"height": <height, integer>,
"width": <width, integer>
},
"thumbnail_crop": {
"center_x": <center X coordinate for thumbnails, decimal>,
"center_y": <center Y coordinate for thumbnails, decimal>
},
// "errors" is set if there were errors. These are grouped by domain. If "errors" is not set, everything succeeded.
"errors": {
"encryption": <encryption error>,
"vision": <vision error>
}
}
}
}There is a prior version of the API, which returned either strings or objects as each URL's result, depending on whether thumbnail crop was requested and successful. It is recommended to use the new, more regular version.
Images API
End users request images from the Images API. Images API is the frontend for serving cached and processed images. The target width and height, result image format and the strategy (mode) to achieve those is specified as query parameters to the Image API.
Image API responds with the processed image ready for display.
Images, other than SVG, can be processed in three different modes. "Fit" will resize the image below the requested dimensions in a bounding box, maintaining the aspect ratio. "Stretch" will change the aspect ratio to fit the requested dimensions exactly, unless source image is smaller. "Crop" will extract an area of the image by either following center_x and center_y parameters, and if they are not set, AI feature detection is performed to find the most interesting part of the image.
SVG images are not processed. GIF and PNG source images requested in GIF or PNG are not processed. These requests are responded to with the source file.
PNG encoded to WEBP is losslessly encoded regardless of the quality setting.
Images are never scaled up.
Source image location is declared in the query path, either as encrypted or relative to the previously agreed origin. All parameters are set in the query string and are optional.
Example URL (clear with a relative origin):
https://data.richie.app/images/v1/TestTenant/2a48f17.jpg?width=450&height=642&dpr=1&mode=fit