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, (animated) GIF, HEIC, WebP, JPEG XL, AVIF, TIFF, PSD, EPS, PDF and SVG files (more possible, just inquire). It also can deliver videos, see the video chapter for more.
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.
| 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 (1) |
| 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 |
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 'https://api.rokka.io/sourceimages/mycompany'
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');
$sourceImages = $client->uploadSourceImage(file_get_contents('image.png'), 'image.png');
var_dump($sourceImages);
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.
The current limit for uploading images are 150 MB in file size. For source images not in the JPEG or WebP format there's an additional limit of 225 Megapixels (equals an image of 15'000 x 15'000 size) .
Instead of directly uploading an image within the POST request, you can also provide an URL to 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]='https://rokka.rokka.io/dynamic/noop/f4d3f334ba90d2b4b00e82953fe0bf93e7ad9912.png' \
'https://api.rokka.io/sourceimages/mycompany'
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');
$sourceImages = $client->uploadSourceImageByUrl('https://rokka.rokka.io/dynamic/noop/f4d3f334ba90d2b4b00e82953fe0bf93e7ad9912.png');
var_dump($sourceImages);
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}' \
'https://api.rokka.io/sourceimages/mycompany'
$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]]]);
// you can also use a metadata object for dynamic metadata instead eg.
// $sourceImages = $client->uploadSourceImage(file_get_contents('image.png'), 'image.png', null, ['meta_user' => ['foo' => 'bar'], 'meta_dynamic' => [new SubjectArea(50, 100)]]);
var_dump($sourceImages);
In case that source image already exists and there are metadata fields which are not defined in the upload, they are not deleted.
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.
When this parameter is set, rokka (losslessly) recompresses TIFF and PSD (to PNG) images when this is set, but leaves the other formats alone (may be extended to other formats in the future). Helpful if you for example have layers from Photoshop. After setting this parameter, the original image (the PSD/TIFF one) will be gone and not retrievable anymore, just the optimized ones.
Additional you can set this parameter to jpg or png. Then rokka will convert TIFF and PSD files to high quality JPEG (or WebP,
if the image is not opaque) or PNG before storing, saving even more space.
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, using the original binary hash generated from the image.
See the Protected Images and Stacks chapter for details.
Paying rokka customers can also upload certain types of non-image files, like Word, Text, etc. This can be helpful, if you want to provide some downloads for such files and don't wanna setup another CDN/file storage just for that.
You can't do image operations on them (it will just show a placeholder image instead), but you can configure a stack to just deliver the original file and use that one.
If you want to start a direct download of such an image and not being opened in the browser,
you can set content_disposition: attachment as stack option.
The allowed file types for this is whitelisted on our side. Ask us, if you need more available.
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 'https://api.rokka.io/sourceimages/mycompany/c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5'
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');
$sourceImage = $client->getSourceImage('c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5');
var_dump($sourceImage);
An example response would be:
{
"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/mycompany/c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5"
}
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 'https://api.rokka.io/sourceimages/mycompany/c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5'
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');
$isDeleted = $client->deleteSourceImage('c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5');
var_dump($isDeleted);
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.
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 'https://api.rokka.io/sourceimages/mycompany?binaryHash=03b3e8a0bdd76ef55c021066642c9d2fa9c02799'
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');
$isDeleted = $client->deleteSourceImagesWithBinaryHash('03b3e8a0bdd76ef55c021066642c9d2fa9c02799');
var_dump($isDeleted);
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
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 'https://api.rokka.io/sourceimages/mycompany/c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5/restore'
$client->restoreSourceImage($hash);
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:
Overwrite: F was sent and the destination exists already.curl -X COPY -H 'Destination: mycompany-stage' 'https://api.rokka.io/sourceimages/mycompany/c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5'
$client->copySourceImage($hash, $destinationOrg)
You can also copy up to 100 images at once for a little bit better performance.
curl -X POST -H 'Destination: mycompany-stage' 'https://api.rokka.io/sourceimages/mycompany/copy' -d '["abcdef","fedcba"]'
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
If you just want to have a fallback organisation, while rendering images (but not for API operations), see the Use another organization as fallback for rendering images chapter.
See searching for images for more details about how to get a list of your images.
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 'https://api.rokka.io/sourceimages/mycompany?binaryHash=03b3e8a0bdd76ef55c021066642c9d2fa9c02799'
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');
$sourceImage = $client->getSourceImageWithBinaryHash('03b3e8a0bdd76ef55c021066642c9d2fa9c02799');
var_dump($sourceImage);
The result is a list with one item in it if anything is found.
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 'https://api.rokka.io/sourceimages/mycompany/c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5/download'
It will return the binary data as the response and contain the name of the file in the header of the response.
If you want to update the name of a source image, you can do this by making a PUT request to
https://api.rokka.io/sourceimages/{organization}/{hash}/name and include the
JSON encoded name in the body:
curl -H 'Content-Type: application/json' -X PUT 'https://api.rokka.io/sourceimages/myorganization/0dcabb778d58d07ccd48b5ff291de05ba4374fb9/name' -d '"somenewname.jpg"'
A source image can be locked to prevent deletion of a source image. It also prevents changes to user metadata.
Only users with an admin or sourceimages:unlock role can change this.
If an image is locked, no one can delete an image before it's not unlocked, not even an admin.
Bash:
curl -X PUT 'https://api.rokka.io/sourceimages/mycompany/0dcabb778d58d07ccd48b5ff291de05ba4374fb9/options/protected' \
--data-raw 'true'
PHP:
$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');
$newHash = $client->setLocked(
true,
'0dcabb778d58d07ccd48b5ff291de05ba4374fb9'
);
JavaScript:
var rokka = require('rokka')({apiKey: 'apiKey'})
var response = rokka.sourceimages.setLocked(
org,
'0dcabb778d58d07ccd48b5ff291de05ba4374fb9',
true
)
We use sha1 for generating hashes and binary hashes of sourceimages, but not for cryptography or other security related matters. All rokka needs is an unique hash per source image and sha1 does guarantee that.
We also separate the storage of images by organization. Images with the same hash in different organizations are treated separately and would not influence each other.