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 enhancements and operations.

Authentication

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 https://api.optidash.ai.com/1.0/account to test your credentials for validity.

# Using HTTP Basic Auth:
curl -u your-api-key: https://api.optidash.ai/1.0/account

# Using Bearer Auth:
curl -H "Authorization: Bearer your-api-key" https://api.optidash.ai/1.0/account

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.

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.

JSON Responses

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

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 provide 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 24 hours from the moment of their creation. A volatile image URL will look like the following:

{
    "url": "https://s3.optidash.ai/temp/13b2a651-a459-4357-8746-8558a429e1a3/image.jpg"
}

If you are using 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": "https://bucket.s3.eu-central-1.amazonaws.com/image.jpg"
}

Using External Storage Providers

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, Cloudflare R2, 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.

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.

HTTP/1.1 429 TOO MANY REQUESTS

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."
}

Errors

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.

HTTP/1.1 422 UNPROCESSABLE ENTITY

{
    "success": false,
    "code": 422,
    "id": "ed06dd8c-9793-4175-b1fa-cae29f657c0f",
    "message": "Super-resolution 'factor' parameter must be a positive integer"
}