Source images


Source images are your original images you upload to Rokka. You should always select the highest quality you can, Rokka will take care of the rest. Usually it's best to use PNG files, as they are not compressed. Rokka can handle PNG, JPEG, GIF, HEIC, WebP, TIFF, PDF and SVG files (more possible, if there's a demand). To ensure the best possible results, we recommend to upload the pictures in sRGB (with or without alpha channel) and not for example in CMYK.

The source image object

Attribute Description
organization Name of the organization that the image belongs to
hash Hash to access the image with, based on metadata. 40 characters long
short_hash A shorter, still unique version of the hash. Can be used instead of the hash. 6-40 characters
binary_hash Sha1 hash of image binary data
name Original filename
format Original format as common file extension
mimetype Original mime type
size Size of images in bytes
width Width of image in pixels
height Height of image in pixels
dynamic_metadata Can contain data that will alter the image identifying hash if altered. See dynamic metadata
user_metadata Contains custom meta data set by the API user that is returned when requesting the source image and can be used for searching. Changing this will not alter the main hash identifying the image. See user metadata
created When this image was created on rokka
link Backlink to itself, useful when you have lists or search by binary hash

Create a source image

You can create a source image with a post to the /sourceimages route and your organization name. It's a simple post with the file data in the body.

In the following example, image.png is a image file in your current working directory and the organization is set to mycompany.

curl -X POST -F filedata=@image.png ''
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');

$sourceImages = $client->uploadSourceImage(file_get_contents('image.png'), 'image.png');


It will return the same meta data as you get from retrieving a single image, with the only difference that it is wrapped in an array for future expansions of multi file uploads.

Create a source image with a remote URL

Instead of directly uploading an image within the POST request, you can also provide an URL do a remote image, which then will be downloaded by rokka and inserted into your repository. This happens synchronously, so you will get the same hashes and metadata back as with directly uploading an image.

The image at the URL has to be publicly accessible. There's currently no way to add authentication. If you need that, talk to us.

curl -X POST -F url[0]='' ''
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');

$sourceImages = $client->uploadSourceImageByUrl('');


Supplying metadata while creating a source image

You can also directly add user metadata or dynamic metadata while creating an image.

curl -X POST -F filedata=@image.png \
             -F 'meta_user[0]={"foo":"bar"}' \
             -F 'meta_dynamic[0][subject_area]={"x":100,"y":100}' \
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');

$sourceImages = $client->uploadSourceImage(file_get_contents('image.png'), 'image.png', null, ['meta_user' => ['foo' => 'bar'], 'meta_dynamic' => ['subject_area' => ['x'=> 50, 'y' => 100]]]);


In case that source image already exists and there's metadata fields which are not defined in the upload, they are not deleted.

Optimizing source images before saving

Sometimes source images contain too much data not really needed for just rendering images. Setting the optimize_source parameter to true can save you some storage space for such cases. Currently rokka (losslessly) recompresses TIFF images, when this is set, but leaves the other formats alone (may change in the future). This saves you some storage space if you for example had layers from Photoshop in your TIFF. After setting this parameter, they'll be gone in the sourceimage and not retrievable anymore.

The binary hash generated for that source image is the one of the original image (before the recompression), and not the one actually stored. So you still can search for that image, if you have to original binary hash generated from the image later.

Retrieve data about a source image

You can retrieve meta data about a source image by providing the identifying hash on the /sourceimages route.

In the following example the organization is set to mycompany and the hash is set to c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5.

curl -X GET ''
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');

$sourceImage = $client->getSourceImage('c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5');


An example response looks like following.

    "hash": "c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5",
    "short_hash": "c03683",
    "binary_hash": "03b3e8a0bdd76ef55c021066642c9d2fa9c02799",
    "created": "2015-08-24T12:17:12+0000",
    "name": "image1.png",
    "mimetype": "image/jpeg",
    "format": "png",
    "size": 131284,
    "width": 800,
    "height": 1160
    "organization": "mycompany",
    "link": "/sourceimages/liip/c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5"

Delete a source image

To delete a source image, you do a delete call on the source images url.

In the following example the organization is set to mycompany and the hash is set to c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5.

curl -X DELETE ''
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');

$isDeleted = $client->deleteSourceImage('c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5');


Deleting a source image will not remove it from the cache. Access to it will fade out as the cache becomes stale. Any new access to a render of a deleted source image will result in a 404 error.

Note: If the image you try to delete does not exist, the API responds with a 404 status code. This 404 can be ignored, though it might indicate a logic error in the client application.

Deleting source images with binary hash

The same binary hash can have different entries in rokka, if they have different dynamic metadata. With this command you can delete all of them at once

curl -X DELETE ''
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');

$isDeleted = $client->deleteSourceImagesWithBinaryHash('03b3e8a0bdd76ef55c021066642c9d2fa9c02799');


With the PHP CLI you can also delete all source images from one organization. Be aware that this may take a while, if you have many images.

./bin/rokka-cli image:delete-all 

Restore a source image

To restore a deleted image and its metadata, do a POSTrequest to /sourceimages/{org}/{hash}/restore.

Returns a 200 http code and the meta data for the image, if the image could be restored. Also if the image wasn't deleted and didn't need to be restored. Returns a 404, if the image could not be restored or was not found.

Images can be restored for 30 days after their deletion.

You can also search for deleted images, if you add the search parameter "?deleted=true" to your searches. See searching for images for more details.

curl -X POST ''

Copy a source image to another organization

To copy a source image to another organization (for example for copying images from a production to a test environment), you can do a COPY request to /sourceimages/{org}/{hash} and send the Destination header with the destination organization. If you send a Overwrite: F header with it, it won't copy it, if it already exists at the destination. Your API user needs to have read permissions on the source organization and write permissions on the destination organization. The memberships endpoint has methods to give an API user access to more organizations.

Returns the following http status codes:

  • 201, if the image was newly created at the destination.
  • 204, if the image was overwritten at the destination.
  • 400, if the destination organization does not exist.
  • 403, if you're not allowed to write to the destination organization.
  • 404, if the source image was not found.
  • 412, if Overwrite: F was sent and the destination exists already.
curl -X COPY -H 'Destination: mycompany-stage' '' 
$client->copySourceImage($hash, $destinationOrg)

With the Go CLI you can also copy all source images from one organization to another, without having to down- and upload them again. Be aware that this may take a while, if you have many images. If that's the case and you need it to be faster, talk to us, we can increase some limits.

rokka sourceimages copy-all $SOURCE_ORG $DESTINATION_ORG

You can also use the PHP CLI for copying a whole organization. But it may be slower than the Go CLI, as it doesn't do parallel copying.

./bin/rokka-cli image:copy-all $DESTINATION_ORG

List source images

See searching for images for more details about how to get a list of your images.

Finding with binary hash

You can limit the outputs of the list by using limit and offset parameters to page through them.

Attribute Description
binaryHash SHA1 hash of the binary file, lowercase hex

In the following example the organization is set to mycompany and the binary hash is set to 03b3e8a0bdd76ef55c021066642c9d2fa9c02799.

curl -X GET ''
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');

$sourceImage = $client->getSourceImageWithBinaryHash('03b3e8a0bdd76ef55c021066642c9d2fa9c02799');


The result is a list with one item in it if anything is found.

Downloading a source image

Should you have a need to download the source image again, you can do so, using this call. This is the only way to get the exact image back. Even if you choose "noop" as a stack operation, rokka will process the image which may alter it.

curl -X GET ''

It will return the binary data as the response and contain the name of the file in the header of the response.