The Optidash Image API is designed to facilitate the intelligent optimization, recompression, and transformation of visual content through straightforward, programmatic HTTP requests. Upon integration of our API, users gain access to a comprehensive range of operations. These include, but are not limited to, resizing, scaling, adjusting, cropping, stylizing, filtering, watermarking, and face detection. This extensive suite of features enables users to effectively manipulate and enhance their visual media with ease.

The core of our API is built upon an AI-powered image optimization and recompression pipeline, as detailed in our image optimization documentation. This advanced technology is designed to significantly reduce the file size of your images while maintaining their visual quality. This foundation enables efficient and effective management of visual content, ensuring optimal performance and user experience.

This document is intended to guide developers in integrating with the Optidash API. It begins with a general overview of the underlying technology and is followed by detailed reference information pertaining to specific image enhancements and operations. This comprehensive resource is designed to equip developers with the necessary knowledge and tools for effective implementation and utilization of the Optidash API.

Authentication

All API requests require authentication using your unique API Key, which can be achieved through either HTTP Basic Auth or Bearer Auth. For HTTP Basic Auth, the API Key should be supplied as the username, with no need for a password. In the case of Bearer Auth, the API Key must be set as the credential in the Authorization header. To verify the validity of your credentials, you can utilize the Account Endpoint at https://api.optidash.ai.com/1.0/account. This ensures secure and authenticated access to the API services.

# 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 use the HTTPS protocol to ensure encrypted traffic. Calls made over plain HTTP or without authentication will not succeed.

Supplying Images for Processing

Images can be provided for processing in two ways: direct upload to the API (Image Upload) or by specifying a publicly accessible image URL (Image Fetch). The recommended method for online visuals is Image Fetch, where a JSON payload with an image URL and processing requests is sent. This approach is quicker than uploading a full binary image representation.

JSON Responses

The API endpoints /1.0/upload and /1.0/fetch return a JSON response, containing metadata for both input and output images, along with a url for the processed image.

Binary Responses

The Optidash API also supports binary responses. If enabled, the API will deliver the final image in a binary format, which can be directly streamed to disk. Metadata related to the API call will be included in the response headers.

Downloading Processed Images

Upon a successful request, the API provides a temporary URL for the processed image, which must be downloaded for use on websites and applications. Note that images in temporary storage are automatically and permanently deleted after 24 hours from their creation time. A temporary image URL will resemble the following format:

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

When using an External Storage provider like AWS S3, the url property will direct to the permanent location in your selected data store, suitable for production use:

{
    "url": "https://bucket.s3.eu-central-1.amazonaws.com/image.jpg"
}

Using External Storage Providers

The Optidash API allows the use of your preferred external storage provider. For instance, if your AWS S3 bucket is configured, you can direct the API to store processed images there. We support major Cloud Storage providers including: AWS S3, Google Cloud Storage, Microsoft Azure Storage, Cloudflare R2, Rackspace Cloud Files, DigitalOcean Spaces, and IBM Cloud Object Storage.

Rate Limits

To protect the Optidash Platform and ensure fair resource distribution, all requests are rate limited per API key, irrespective of the HTTP method or endpoint. Rate limits are set in 15-minute intervals, allowing up to 100,000 requests every 15 minutes (approximately 110 requests per second). Each response includes standard X-RateLimit-* headers to help you monitor your usage.

Exceeding an API rate limit results in an HTTP 429 Too Many Requests response, with additional information in the JSON body about the exceeded limit and the reset time.

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

The Optidash API uses standard HTTP response codes to signify the success or failure of an API request. Successful requests typically result in a response within the 2xx code range. Codes in the 4xx range often imply an issue with the request itself, such as a missing required parameter. Responses in the 5xx range usually indicate a server-side problem, suggesting difficulties on our end in fulfilling the request.

Each API response includes an HTTP status code and a success property in its JSON format. For erroneous calls, the success property will be marked as false, accompanied by a detailed error message. In cases where you need to contact us regarding a specific request, including the request id will expedite 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"
}