Skip to content

Process images with Imaginary

This example uses Imaginary, an HTTP microservice for high-level image processing. Imaginary can be deployed as KraftCloud service and can be queried via HTTP to process images.

To run this example, follow these steps:

  1. Install the kraft CLI tool and a container runtime engine, e.g. Docker.

  2. Clone the examples repository and cd into the examples/imaginary/ directory:

Terminal window
git clone
cd examples/imaginary/

Make sure to log into KraftCloud by setting your token and a metro close to you. We use fra0 (Frankfurt, 🇩🇪) in this guide:

Terminal window
# Set KraftCloud access token
# Set metro to Frankfurt, DE

When done, invoke the following command to deploy this application on KraftCloud:

Terminal window
kraft cloud deploy -p 443:8080 -M 256 .

The output shows the instance URL and other details:

Terminal window
[] Deployed successfully!
────────── name: imaginary-mwb4y
────────── uuid: 8cf18bf7-2bf6-4f23-be07-f9c234c7962d
───────── state: running
─────────── url:
───────── image: sha256:673834bc531038bb621266f7fd635a04e559050cbe82876df811fd4b975ea4fe
───── boot time: 32.26 ms
──────── memory: 256 MiB
service group: divine-wind-1ycjvhqs
── private fqdn: imaginary-mwb4y.internal
──── private ip:
────────── args: /usr/bin/imaginary -p 8080

In this case, the instance name is imaginary-mwb4y and the URL is They are different for each run.

Use curl to query the KraftCloud instance of Imaginary. You will get a health status of the service:

Terminal window
curl -s | jq
"uptime": 414,
"allocatedMemory": 0.19,
"totalAllocatedMemory": 0.72,
"goroutines": 6,
"completedGCCycles": 13,
"cpus": 1,
"maxHeapUsage": 3.63,
"heapInUse": 0.19,
"objectsInUse": 846,
"OSMemoryObtained": 7.73

To test the Imaginary instance on KraftCloud use the /form endpoint. That is, open the URL in the browser and use the existing forms to process an image.

To make actual use of the Imaginary instance, use the endpoints of the HTTP API. Endpoints are provided, together with parameters, for different image processing options: /crop, /resize, /flip, /convert, /watermark, /rotate, /blur etc.

At any point in time, you can list information about the instance:

Terminal window
kraft cloud instance list
imaginary-mwb4y running 54 seconds ago sha256:673834bc531038bb621266f7fd635a04e5... 256 MiB /usr/bin/imaginary -p 8080 32262us

When done, you can remove the instance:

Terminal window
kraft cloud instance remove divine-wind-1ycjvhqs

The Imaginary KraftCloud service mostly works as is: you deploy it and then you query the endpoints of the HTTP API. You can customize the command line options used to start the service, by updating the cmd line in the Kraftfile:

spec: v0.6
runtime: imaginary:1.2
cmd: ["/usr/bin/imaginary", "-p", "8080"]

You can update the cmd line with command line option for Imaginary.

Learn More

Use the --help option for detailed information on using KraftCloud:

Terminal window
kraft cloud --help

Or visit the CLI Reference.