On this page:

The Optidash Image API enables you to intelligently optimize, recompress, and transform your visual content in a simple, programmatic way using conventional HTTP requests. Once you integrate our API, you will gain access to all operations including — but not limited to — resizing, scaling, adjusting, cropping, stylizing, filtering, watermarking, and face detection.

The very foundation of our API is built on top of AI-powered image optimization and recompression pipeline allowing you to slash the byte size of your images while retaining their visual quality.

This document provides developers with information on how to integrate with the Optidash API - a general overview of the technology that has been implemented, followed by reference information about specific image operations.

Code Samples

At the bottom of each section, you'll find code samples that show how to perform a specific image operation, select a response method or use External Storage across all our official integrations.


All requests to the API must be authenticated with your unique API Key using either HTTP Basic Auth or Bearer Auth. When using HTTP Basic Auth you must provide your API Key as the username value. You do not need to provide a password. If you need to authenticate via Bearer Auth using the Authorization header, you must set your API Key as credentials. You may use the Account Endpoint to test your credentials for validity.

# Using HTTP Basic Auth:
curl -u your-api-key:

# Using Bearer Auth:
curl -H "Authorization: Bearer your-api-key"

All API requests must be made using the HTTPS protocol so that traffic is encrypted. Calls made over plain HTTP will fail as well as requests without authentication.

cURL uses the -u flag to pass basic auth credentials. Adding a colon after your API key will prevent it from asking you for a password.

Supplying Images for Processing

You can supply your images for processing in two ways - by uploading them directly to the API (Image Upload) or by providing a publicly available image URL (Image Fetch). If you already have your visuals available online, we recommend using Image Fetch by default. That way you only have to send a JSON payload containing an image URL and requested processing steps. This method is much faster than uploading a full binary representation of the image.

Supported Image Formats

The Optidash API supports all major image formats in modern Web and Mobile development as well as Digital Photography. It covers a wide range of both input and output image formats and their variations.

Output image formats:JPEGJPEG2000PNGAnimated PNGGIFAnimated GIFWebPHEIC

Choosing Response Method and Format

For every request to the image processing endpoints /1.0/upload and /1.0/fetch, the API will return a JSON response with the metadata pertaining to both input and output images as well as a url property of the processed image.

Binary Responses

The Optidash API also allows you to use binary responses. When enabled, the API will respond with a full binary representation of the resulting image and you can safely stream that response directly to disk. Any metadata pertaining to that API call will be transmitted in the response headers.

Downloading Processed Images

For every successful request, the API will return a volatile URL of the resulting image that needs to be downloaded and served on your websites and applications. All images within the temporary storage are automatically and irreversibly deleted after one hour from the moment of their creation. A volatile image URL will look like the following:

    "url": ""

If you are using the Optidash CDN or an External Storage provider such as AWS S3, the url property will always point to the permanent location within your data store of choice and you can safely use those URLs in production:

    "url": ""

Using External Storage Providers

The Optidash API gives you flexibility and freedom of using your external storage provider of choice. For example, if you already have your AWS S3 bucket configured you can instruct the API to store processed images there. We support all major Cloud Storage providers: AWS S3, Google Cloud Storage, Microsoft Azure Storage, Rackspace Cloud Files, DigitalOcean Spaces and IBM Cloud Object Storage.

Rate Limits

In order to protect the Optidash Platform and to ensure an equitable distribution of the system resources, all requests, regardless of the HTTP method and endpoint used, are rate limited on a per-key basis. Rate limits are divided into 15 minute intervals and you may issue up to 100,000 (one hundred thousand) requests every 15 minutes, which is more than enough for reasonable usage (that's around 110 requests per second). You'll find standard X-RateLimit-* headers in every response in order to help you track your usage.

X-RateLimit-Limit: 100000The number of allowed requests in the current period
X-RateLimit-Remaining: 2120The number of remaining requests in the current period
X-RateLimit-Reset: 778The number of seconds left in the current period
If you need to process a large batch of images very quickly and have a sound and solid reason for this, please open a support ticket with us and we may temporarily raise rate limits for your account.

If your API Key exceeds an API rate limit, the service will return an HTTP code of 429 Too Many Requests and the body of the JSON response will provide additional information about the rate limit reached and when the limit will be reset.

Retry-After: 778

X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 778

    "success": false,
    "code": 429,
    "id": "594941b7-db16-45e1-a5b5-6e8cbf3b604f",
    "message": "Rate limit exceeded. Retry in 778 seconds."


The Optidash API returns conventional HTTP response codes to indicate the success or failure of an API request. A successful request will always result in the 2xx code range. Status codes in the 4xx range typically indicate that there was an issue with the request that was sent (for example a required parameter was omitted). If you receive a status in the 5xx range, this generally indicates a server-side problem and means that we are having an issue on our end and cannot currently fulfill your request.

For every API request, the JSON response will also include an HTTP status code and success property. In the case of an erroneous call, the success property will be set to false and a descriptive error message will also be provided. If you need to contact us about a specific request, providing the request id will ensure the fastest possible resolution.


    "success": false,
    "code": 422,
    "id": "ed06dd8c-9793-4175-b1fa-cae29f657c0f",
    "message": "Adjust 'contrast' parameter must be an integer within -100 to 100 range"
Grace Przemek Magda Damian
Have questions? Let's talk!We usually respond in just under an hour

Thanks for reaching out!

We've received your message
and will get to it as quickly as possible.

Whoops, looks like something went wrong.

We encountered an unexpected error and cannot complete your request. Please try reloading the page.