The SupaRes API enables you to enhance, optimize, 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 — super-resolution, face enhancement, low-light boost, tone adjustments, and noise removal.

This document provides developers with information on how to integrate with the SupaRes 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.supares.com/1.0/account to test your credentials for validity.

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

# Using Bearer Auth:
curl -H "Authorization: Bearer your-api-key" https://api.supares.com/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.

Asynchronous Requests

AI image enhancement requires enourmous amounts of GPU compute power. In order to prevent exhaustion of compute resources during bursts of incoming traffic, all requests to the SupaRes API are asynchronous.

For every request to the image processing endpoints /1.0/upload and /1.0/fetch, the API will immediately return a unique request id with status code 202 Accepted.

HTTP/1.1 202 ACCEPTED

{
    "success": true,
    "code": 202,
    "id": "f26656d4-3322-4279-acf4-0e1b3ef9d4bd"
}

The SupaRes API exposes a /1.0/results/{id} endpoint that you may use to obtain the results of your request using a simple polling mechanism. For example:

curl -u your-api-key: https://api.supares.com/1.0/results/f26656d4-3322-4279-acf4-0e1b3ef9d4bd

Webhooks

Another way to obtain the results of your requests is by using Webhooks. You may instruct the API to send a Webhook to your endpoint of choice once the processing of the request is finished.

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

{
    "url": "https://dl.supares.com/50/59/66/3f/e7b6-418d-a4cd-af0a7e478134/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"
}

Rate Limits

In order to protect the SupaRes 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

The SupaRes 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"
}