API: Main Concepts
Temporary image store
The server uses a temporary image store, accessible through /images. Images can be uploaded to that store, and downloaded from that store. Every image on that store has a unique ID derived from its content¹, and written as 64 hex digits, e.g.
0a6677d80420b2a83473f36d2625f38e675c5d7e1efaa6edb861f69cba4d9b59
Images are automatically removed by the store if they have not been used for more than 1 hour (configurable). Whenever an image is accessed, its expiration is extended.
The image store is not limited to storing images. Any file can be stored there.
1. The image ID is the SHA256 sum of the content.
Image processing
Image processing algorithms analyze or transform images. The parameters are passed with the request URL, and the result is returned as JSON object in the response body.
Images are thereby referenced by image ID. The input image is loaded from the image store, and the output image is saved back to that store. The output image may be downloaded, or used as input image for another image processing request.
Many commands repeat the request parameters in the response, indicating what they interpreted and used when producing the result.
One-request image processing
Most image processing algorithms also accept the input image to be uploaded with the request. In this case, the input image ID is omitted, and the desired image is passed in the request body. The server will send the resulting image in the response body.
Using this, an image can be processed with a single request. The input and output images are not stored to the image store, but deleted immediately after processing.
Accepted image formats
The following file formats are accepted for processing images:
A number of other image formats (BMP, GIF, TIFF, WebP, ...) are accepted for conversion to one of the above formats. The system auto-detects the image format.
Errors
If the request is invalid, or if a technical error occurs on the server, an appropriate HTTP response code (400, 404, 500, ...) is returned.
In case image processing fails, the returned JSON object contains an error key with a message describing the error.