Getting started

Vault8 is a real-time manipulation service for uploading, storage, administration and delivery any images that can be found on the Internet. This document gives a detailed description of all functionalities available in Vault8 and includes examples that show how to use them.

About Vault8

Vault8 is a functional and reliable service that allows you to upload and process images in real time. Vault8 is designed to be fast and easy to use. The software product allows you to manage large amounts of images with minimal memory and time resources. It improves the data on the fly by choosing the optimal parameters for the receiver. With the software, you can instantly receive various modifications of any remote image and deliver it to your customers.

Vault8 usage reduces the number of image manipulating code to a simple request to the service. The software provides API for fast access directly from your users’ browsers. It offers secure data storage and quick access to them through caching, routing and CDN. Vault8 proposes Amazon S3 as a long-term storage and a local storage to avoid image re-uploading. The product use allows our customers to optimize their applications, increasing performance and expanding capabilities.

Why Vault8

The Vault8 is aimed at combining the advantages and correcting the shortcomings of similar products. Their main problem is that they focus exclusively on giant or tiny projects. Serious functional services require thorough preparation and adjustment to start using. Easy-to-use products have limited capabilities and low security. So the main principles of Vault are:

  • flexibility and customizability for various user needs;
  • reliability while uploading, storage, processing and delivery images;
  • simplicity at all stages of product use.


With Vault8 you need not store hundreds versions of any image - you can upload the only one and get its modifications dynamically. Resizing, cropping, autoorientation, adding labels and watermarks, combining images and other filters are supported. Test them right now on interactive examples. The combination of different filters with the necessary parameters will make it possible to obtain an optimal image for each case. Vault8 supports JPEG, PNG, and GIF image formats.

Vault8 offers solutions for companies of all sizes. You can choose one of three possible tariffs depending on your goals and requirements. You can go from one plan to another at any time without any effort if you are short of proposed opportunities. You can also install Vault8 on your own server with the required characteristics.

The service supports smart caching on some levels. Firstly, Vault8 remembers the original images you have recently accessed. Secondly, it caches modified versions of the images on the server. Vault8 allows you to specify the maximum amount of cached data. The originals will be automatically deleted if no new images have been created recently on their basis. Generated from the original cached images will be removed if they are not referred for a long time.


Processing large amounts of remote images, storing and delivering them to customers are always accompanied by risks. We prevent and minimize possible dangers at all stages of using our service. The service suggests using reliable storages, image URL signatures, fast delivery thanks to CDN or a caching.

You are able to use your own S3 storage. Vault8 syncs with Amazon S3 which ensures that as much images as you need are stored and transmitted securely.

It also allows upload images securely. Vault8 provides secure URLs to prevent others from sending new requests to the service on your behalf. Such URLs contain additional protection signature at the end of the query string which is generated using SHA1 algorithm.


Vault8 is simple enough to set up and use. The service allows you to download images directly from the browser without preliminary uploading to the server.

To get access to its functionalities you should go through some simple steps in Installation guide to set up and configure environment variables for your server. Our assistance in installation at the client’s server is included. To get starter and startup plans you just have to sign up.

The only thing you need to use Vault8’s features is adding simple parameters to image URLs in query string (perhaps, in an IMG tag) in special format. You can find additional information about Vault8 in documentation.

If you still have questions or need technical support, please, do not hesitate to contact us by e-mail.

Installation guide

When you start to go beyond possibilities of the starter and startup plans, you can easily switch to enterprise one. In this case the Vault8’s software is run on your own server. The number of available image requests and bandwidth is conditioned by the server parameters. This tariff is best suited for applications with heavy load. Our guidance and assistance in installation at the client’s server is included.

Performance and requirements

Vault8 is based on Erlang virtual machine Beam and is able to be run on any Linux platform. It requires minimum 512 megabytes memory and PostgreSQL version 9.5. To get started with any of Vault8’s tariff plans, you need to sign up and receive your account’s public and private keys.

Installation process

Check out the steps below to set up and start using Vault8 on your server.

  • Get the Vault8 package by contacting the development team at
  • Make sure you have installed PostgreSQL version 9.5. Otherwise, set it.
  • Install all necessary dependencies with the command: apt install imagemagick pngquant gifsicle jpegoptim libpq5 libpq-dev. Note that the ImageMagick package must be version 6.9.7 or higher.
  • Create directories where your images will be stored. You need separate folders to save origin and modified images as well as images which were generated with key words ‘new’ and ‘sample’. You also should create a separate folder for blank images that will be shown instead of requested images in case of any mistake. Paths to these directories will be specified in the environment variables. A list of all variables with explanations and default values is given below.
  • Run migrations in the next way: bin/vault106 command 'Elixir.Vault106.Release.Tasks' migrate.
  • Run the file bin/vault106 to start Vault8 on your server.
  • Configure environment variables to set up a system for yourself.

Environment variables

  • Application configuration
VAULT8_HEADER_SERVER_NAMEVault8Default application server name
VAULT8_MAIN_URLhttps://vault8.ioDefault application URL
APP_NAMEvault106Default application name
APP_1_DOMAINvault8.ioDefault application domain
APP_1_PORT3000Default application port
ENABLE_AUTHfalseNeed to use authentication for the application. If the value is true, Vault8 will use secure URLs with signature protection
DATABASE_URLSpecify connection to your PostgreSQL database in such way: postgres://user_name:password@ip:port/vault8_production
CROSSDOMAINS*Specify domains which can get access to your server application. There are no restrictions by default

  • Image storage configuration
VAULT_UPLOAD_LOCAL_FOLDER/uploads/local/Path to save origin images on local storage
VAULT_UPLOAD_CACHE_FOLDER/uploads/cache/Path to cache modified origin image copies
VAULT_SAMPLE_FOLDER/uploads/sample/Path to store images that can be used as samples when generating a random image. Note, that all these images’ names must consist of their number from zero to the required value. By default, the directory includes 50 numbered images with ‘jpg’ extension. If you need other format images just add them to the folder
VAULT_BLANK_FOLDER/uploads/blank/Path to store blank images which will be shown instead of requested images in case of any mistake
VAULT_NEW_FOLDER/uploads/new/Path to store basics for new images (.gif, .png and .jpg) generated with a Vault8’s key word ‘new’ and used as their backgrounds. You can select your own basics instead

  • Image amount configuration
IMAGEMAGICK_PROCESS_AMOUNT10The maximum number of processors which may be used to process requests to Vault8
CACHE_IMAGES_AMOUNT30Maximum cache capacity for modified image copies
CACHE_IMAGES_LEAVE_DAYS30Duration of image storage in cache
CACHE_IMAGES_EVERY3600000Frequency of updating image cache, by default, every hour (in milliseconds)
LOCAL_STORAGE_IMAGES_AMOUNT100Maximum local storage (not cache) capacity for origin images (amount of photos)
LOCAL_STORAGE_SIZE_BYTES5242880Maximum local storage capacity for origin images in bytes
LOCAL_STORAGE_IMAGES_EVERY18000000Frequency of updating local image storage in order to find and delete outdated images (in milliseconds)

  • Remote storage configuration
REMOTE_STORAGERemote storage identifier. Can be “s3” for Amazon S3, empty or absent. Support for other storages will be added later
AWS_ACCESS_KEY_IDAmazon S3 access key ID
AWS_SECRET_ACCESS_KEYAmazon S3 secret access key
AWS_S3_BUCKET_NAMEAmazon S3 bucket name
AWS_S3_REGIONAmazon S3 region, e.g. “eu-central-1”

How it works

Vault8 allows you to manage great numbers of images with minimal memory and time consumptions on both web and mobile cloud-based applications. Vault8 offers an end-to-end solution for all your image needs: storage, enhancing and delivery. Uploading one image, you get an ability to generate various sized and modified ones from your original to fit any device and users’ needs. Using better-optimized images helps to increase application performance and get them to the customers faster. Moreover, the images will also be automatically scaled to handle any high load and bursts of traffic. Vault8 uses Amazon S3 as a long-term storage. The service lets to avoid waste of time while waiting for images re-upload due to cashing of last access files.

Vault8 is designed to be fast. It may take longer to transit/download the image than to have it processed by Vault8. In effect, processed images are delivered as fast as the original ones, or even faster (due to caching and CDN). Learn more about Vault8 before you start using it.

The only thing you need to use Vault8’s features is adding simple parameters to image URLs in query string (perhaps, in an IMG tag) in such format: Vault8 will do the rest. You can find image API and possible filters below. The service also provides an internal API for managing your applications and tracking statistics on Vault8’s usage.


Supported images

Vault8 supports JPEG, PNG, and GIF image formats. If you need to render images in different formats, please, do not hesitate to contact us. By default, we limit the maximum image size to 10 megabytes in Starter and 50 megabytes in Startup plans. Enterprise plan proposes unlimited images size, so you’ll be able to configure it on your load balancer (e.g. on Nginx).

Remote storages

Vault8 can be integrated with popular remote storages (such as Amazon S3) which ensure that all your data are kept in safety. Moreover, it provides some ways to accelerate image processing thanks to smart caching and usage of any existing CDN.

At its entry-level configuration, Vault8 can process 60 unique images per minute. Processing of re-access to any version of photo takes 1 millisecond.

Vault8 supports some levels of image storages:

  • a remote storage;
  • a local storage for file originals which are often addressed to generate new copies;
  • a cache folder for keeping processed images which were recently looked through.

Note, that Vault8 uses CDN only as a long-term repository to store images which are not frequently addressed, but not for data delivery. Whenever a new file should be processed, Vault8 appeals to the remote repository itself. Top requested images, in turn, are stored locally, as well as the cached different versions of the same picture.

The local storage size and the cache folder size are determined by the configuration. To cope with any increased load and to reduce the response time, these values can be enlarged. Use the environment variables to configure Vault8’s local and cache directories for your needs. Extra original images will be automatically deleted from the local storage if new copies were not recently created on their basis. Cached versions will be removed if they were not referred for a long time.

Remote storages can be set up with the the Vault8 API. Note, that you can use a unique configuration file for each application. When a remote storage is connected, Vault8 provides the synchronization of all existing files, including those which were added to your repository before.

Different remote storages support will be available in the nearest future.

Image Uploading

With Vault8, you can easily upload images to the cloud and automatically perform smart image manipulations without need to install any complex software. There are three options for easy image upload via Vault8’s secure and comprehensive API: from a server-side code, directly from the browser and from a mobile application. You can use Vault8’s API either directly or through one of Vault8’s client libraries (SDKs). The SDKs wrap the upload API and simplify integration with web sites and mobile applications.

The uploaded images can then be converted to all the relevant formats suitable for web viewing, optimized for web browsers and mobile devices, normalized, manipulated in real time and delivered to users through a fast CDN.


If you want to upload images within the direct call to API from your custom code, you need to send a POST request to with special parameter: file or url.

The parameter name where the file content should be located is file. The parameter can be placed both in a standard multipart/data title, and in the body. The file may be sent either unchanged (as a byte array), or base64-encoded.

Alternatively, instead of the file parameter you can also send the url parameter with the image address. Vault8 will use this URL to download and process the image, in a usual way.

As the result of upload-request you will get a JSON-response with unique image_uid key identifier and status of operation. Here’s an example:

    image_uid: '5ec25a9252724b839a12891f733d.png',
    status: 'success'

To get access to the uploaded image file later (generate links to it) you should save gotten unique identifier.

Sample image

Each request to service contains image unique identifier. Vault8 provides special type of images for testing the system in a developer mode. Any of such sample image identifiers must begin with keyword sample followed by any set of characters except comma and slash. Using ASCII-characters is preferable for simplicity of link generation. For example: sample-w57yhieoyrgo8qwfga or sample-abra-kadabra. For any request you will get some picture from a collection depending on this random set of characters. In the self-hosted solution proposed by the Enterprise plan, images samples can be stored in a configurable folder.

Empty image

In certain cases, it may be necessary to start generating a new image instead of using the existing one. To do this, just use the new keyword instead of image identifier in your upload request, that will lead to generating an empty image. Make sure you specify the image size as the first parameter. It is better to use resize_fill for this.

Secure URLs

The number and bandwidth of processed images are limited. Secure URLs prevent others from generating Vault8 image URLs on your behalf. Such URLs contain additional GET parameters at the end of the query string.

By default, all URLs are security-signature protected, including the upload URL. Two keys will be provided for each application: public and private ones. A private key is not available to users. A signature-protected link will be generated in the same way as a non-protected link, with additional GET parameters:

  • p - unchanged public key provided for each application.
  • time - the time of the link generation in Unix format, specified as the number of seconds elapsed from the midnight (00:00:00 UTC) of January 1, 1970. This is an optional parameter.
  • until - the time until each link will be valid. After this moment occurs, the link will become void, and a single-pixel 500-error image will be placed instead. For generation a link to the image, this is an optional parameter. For generating the /upload link, this parameter is compulsory. Be careful, as you generate the /upload link with quite a large period of validity. Note that this link will be available in a browser, so users will be able to save it for their own needs and use aside from the application. The decision is setting the validity period of such links equal to the duration of your main application session.
  • s - this is a signature string generated using private and public keys. The rule of its generation is as follows. First, the following strings are generated:
    • PUBLIC is a public key generated for the application only once. Example: 46951689456218457dd0ef8;
    • PRIVATE is a secret key generated for the application only once. Example: ec3906ae9a4ac272a66edc8f5a3baa82e4caf62f;
    • PATH is a complete get path, which begins with a leading slash and includes image identifier, parameters and name. Example: /sample-abrakadabra/autoorient,grayscale/name.jpg
    • CURRENT_TIME is time in Unix format. Example: 1491172587 (this number corresponds to the date of 2017-04-02 22:37:00 +0000). This parameter serves for generation of a variety of URLs for the same image.
    • UNTIL_TIME is time in Unix format. Example: 1491246600 (this number corresponds to the date of 2017-04-02 19:10:00 +0000). This parameter is needed to prevent a once-generated URL from being used after a certain time has elapsed.

      Then all these strings are concatenated and separated by the vertical slash (`|`) like in the following template: PUBLIC|PRIVATE|PATH|CURRENT_TIME|UNTIL_TIME. For the above mentioned examples this should result in the following string: 46951689456218457dd0ef8|ec3906ae9a4ac272a66edc8f5a3baa82e4caf62f|/sample-abrakadabra/autoorient,grayscale/name.jpg|1491172587|1491246600. If parameters of CURRENT_TIME and UNTIL_TIME are not used, they should be disregarded as if never existed. For example: 46951689456218457dd0ef8|ec3906ae9a4ac272a66edc8f5a3baa82e4caf62f|/sample-abrakadabra/autoorient,grayscale/name.jpg

      Afterwards, SHA1 function is taken for the above string. In the example we use, the resulting string should be 460cdb1b41bdcfd9487c2ddfb15f386ebcd76a5f. If the time parameters are absent, the resulting string should be: 03c7d80360d914c7e2f628275def2aafb0953a8f.

      Then all the characters received after SHA-1 operation must be written in reverse order: f5a67dcbe683f51bfdd2c7849dfcdb14b1bdc064 (for generating URL with no optional time parameters, the reverse order string should be f8a3590bfaa2fed572826f2e7c419d06308d7c30). The result is the value of s parameter in secure image URL.

As a result of all the above steps, we will get the URL like that:,grayscale/name.jpg?p=46951689456218457dd0ef8&s=f5a67dcbe683f51bfdd2c7849dfcdb14b1bdc064&time=1491172587&until=1491246600. Or like that for string without optional parameters:,grayscale/name.jpg?p=46951689456218457dd0ef8&s=f8a3590bfaa2fed572826f2e7c419d06308d7c30.

Image API

All the image links are generated according to the following principle:,filter2,filter3-param1/anyname.extension


  • imageid is a unique image identifier obtained when the image is uploaded to the server.
  • anyname is any arbitrary image name. Its purpose is: whenever a user needs to save an image to his/her disc space, they will use a predefined name instead of the choosing a new one.
  • extension is a file extension. Whenever Vault8 does not support a certain file, that file will be returned unchanged. The list of supported formats can be found in supported images section.
  • filter is one of twenty four supported image filters. All the possible filters are separated by commas, while filter parameters are separated by a dash. Each filter can contain from zero to four compulsory parameters. Dash, vertical slash, and comma are not allowed in filter names and parameters.

Internal API

With Vault8 you are able to manage several applications which use the service independently. Special API allows you to control and get statistics on Vault8’s usage by your applications. When making requests to the Vault8’s API, you need to add x-api-token in the HTTP request header. The API returns all responses in JSON format.

Manage applications

To look through the list of all applications, send a GET request to /api/applications. Here’s an example: curl -H "x-api-token: aw74ihfysrsgy75ow4jkhjbsguvfydihsejo5wjnhejbsug" As a result you will get an array of objects in the following format:

    uid: string,
    enabled: boolean,
    public_token: string,
    private_token: string,
    description: string,
    is_remote_storage_connected: boolean,
    total_requests: {
      generation_count: integer,
      requests_count: integer
    local_files: {
      total_count: integer,
      total_size: integer
    remote_files: {
      total_count: integer,
      total_size: integer


  • uid - the application unique identifier;
  • enabled - the application status (true or false) to enable or disable it;
  • public and
  • private token - keys for generation image signature-protected URLs;
  • description - some data about the application, an empty string by default;
  • is_remote_storage_connected - specifies if a remote storage is used;
  • total requests - a general number of requests to the Vault8 service through the application which includes number of image generation (modifications with filters) and read requests (image uploads);
  • local files - a number of locally stored files and their total size in bytes;
  • remote files - a number of files in a remote storage and their total size in bytes.

This request lets you know to what extent you are using the capabilities of the service and whether your tariff plan is sufficient for your needs. To find out the same information about a particular application, you need to specify its uid at the end of your GET request: /api/applications/uid.

To create a new application, send a POST request to /api/applications specifying its uid and description. Use a PATCH request to a particular application /api/applications/uid to update its description field.

You are also able to execute a DELETE request to some application. This will not remove it from the list but change its enabled status to false. Use a POST request to a specific application /api/applications/uid to enable it.

Manage files

The list of all available image files can be gotten with the GET request to /api/applications/uid/files. As a result, the following short data about each file will be received:

    uid: string,
    cache_generations_amount_requests: integer,
    cache_generations_count: integer,
    type: string,
    created_at: datetime


  • uid - the file unique identifier;
  • cache_generations_amount_requests - how many times a specific image was looked through;
  • cache_generations_count - how many times a specific origin image was accessed to generate new copies;
  • type - the file type;
  • created_at - a date of the file creation.

You can also get a detailed information about a specific file, ending your GET request with its identifier fid: /api/applications/uid/files/fid. In this case you will get a similar JSON response with additional fields:

    versions: {
      amount: integer,
      processors: {
        value: string,
        params: array of strings


  • amount - how many copies (processed files) a particular image has;
  • processors - a set of filters and their parameters applied to these images;

You are able to send a DELETE request to a specific image /api/applications/uid/files/fid to remove it.

Remote storages

If some of your applications are using remote storages, you are able to get and update their configuration files independently with the API. Send a GET request to a specific application /api/applications/uid/remote to see the current settings in the following format:

    type: remote_config.type,
    params: remote_config.params

Send a similar PATCH request to update the configuration file params of a selected application.

Supported filters


If the image has been inverted, the filter is used to give it the desired orientation. To apply the filter, you only need to add autoorient (or auto_orient) to the URL.


This filter allows setting the background color, which replaces transparent color. Semitransparent colors will be mixed with the background color. Its format is: background-color, where color may be specified either in a hexadecimal format (for instance, ffffff or 867783), or by one of predefined words. List of colors, their names and hexadecimal representations can be found on a special page.


To crop an image, you need to specify four parameters. They are w and h dimensions (width and height of the crop rectangle), and the origin x and y (which define the top left point coordinates of the crop rectangle). Its format is: extract-#{w}-#{h}-#{x}-#{y}. The word crop can be used as alias of extract. In this case filter format will look like that: crop-#{w}-#{h}-#{x}-#{y}.

Resize fit

This filter operation has two options:

  • It resizes your images maintaining its proportions. The new size is calculated based on the image width input by a user. Its format is: resize-fit-#{w}-#{h}.

  • Alternatively, it generates a new image based on the specified parameters. Proportions of the origin image remain unchanged. All the empty space of the image will be filled by a selected color. Its format is: resize-fit-#{w}-#{h}-#{c}, where {c} means a color. These colors are assigned similar to background. We select the width and height parameters, and the images will be scaled according to the width value. The rest of the space will be filled by a selected color.

Resize limit

The resize_limit filter is similar to resize_fit above. But unlike the previous filter, it can not increase the size of a small image to the specified parameters.

Resize fill

The resize_fill filter changes the image size exactly according to the given parameters. Its format is: resize-fill-#{w}-#{h}.


The watermark filter adds a watermark above the image. Its format is: watermark-WTMRKUID-POSITION-SIZE, where:

  • WTMRKUID is an identifier of the image that represents a watermark. In the self-hosted solution available from the Enterprise plan, this can be a name of the image in the watermark folder.

  • POSITION is a watermark position, that may take the following values: center, centertop, centerbottom, leftcenter, leftbottom, lefttop, rightcenter, rightbottom, righttop, overcenter, undercenter.

  • SIZE. A watermark size depends on the image size and this parameter. This value is used to setup the proportion of the watermark size. The values may be xs, s, m and l (from the smallest to the largest).

Any of the images previously uploaded into Vault8 can be used as a watermark. What you only need to do is to insert WTMRKUID.


It creates an image of a specified size that is filled with a certain number of other images. First, you need to specify the resulting image size, using the resize_fill filter. The tile filter itself has a floating number of parameters, which can include optional dimension values (X, Y - the number of displayed images horizontally and vertically) and any number of images (their identifiers) shown on the screen. The filter can be used in one of the following ways:

  • If the dimensions are not assigned by the first two parameters, it will be calculated automatically in the most efficient way. For example, a 3x3 net will be generated for five images, and a 4x4 net – for 10 images: tile-imageuid1-imageuid2-imageuid3-imageuid4....

  • If only one dimension is assigned, the second will be automatically calculated to show all the available images: tile-X-imageuid1-imageuid2-imageuid3-imageuid4....

  • If both dimensions are assigned, the redundant images will be ignored: tile-X-Y-imageuid1-imageuid2-imageuid3-imageuid4....


This filter sets the quality of the output image, using values between 0 and 100. This setting affects only JPEG images. Its format is: quality-n, where n is the expected level of quality. Higher quality values use images with a larger file size.


The filter allows blurring the image with a relative blur coefficient from 0 to 100. Its format is: blur-r, where r is the blur radius in pixels.


It regulates the brightness of the image. No parameters values are used. To apply this filter, you only need to add brightness to the URL.


It adjusts the contrast of the image, with values from 0 to infinity. 0 is the minimum value. The filter’s format is: contrast-n, where n is a level of contrast.


This filter is designed to darken your images. To apply this filter, you only need to add gotham to the URL.


This filter makes your images black and white. To apply this filter, you only need to add grayscale to the URL.


This filter gives your images some retro look by increasing the green, brown and orange tones and adding some brightness. To apply this filter, you only need to add kelvin to the URL.


This filter adjusts the hue of the image, with values between 0 and 299. The default value is 100 (no hue adjustment). Its format is: hue-n, where n is a number.


To add the pin, you need to specify five values: coordinates of the pin #{x}-#{y}, the text label (one letter identifier) of the pin S, color of the pin CP and color of the pin background CF. Its format is: pin-#{x}-#{y}-S-CP-CF.


Adjusts the saturation of the image, with values from 0 to infinity. 0 is the minimum value. Its format is: saturation-n, where n is a number.


This filter makes your images sharper. To apply this filter, you only need to add smartsharp to the URL (no values are used).


This filter gives your images dark soft light. To apply this filter, you only need to add soft to the URL (no values are used).


This filter gives your images some burnt, aged look. Vignetting is also added. To apply this filter, you only need to add toaster to the URL (no values are used).


This filter adds some contrast and saturation to your image to create a feel of using an old color film. To apply this filter, you only need to add vintage to the URL.


This filter adds some darkening at the corners of your image. You only should enter vignette to the URL.