Introduction

Introduction

On this page:
Intro ▾
{{activeSubMenu.text}} ▾

The Pixaven Image API allows you to perform blazingly fast advanced image transformations in a simple, programmatic way using conventional HTTP requests. Once you integrate our API, you will have access to all image transforming operations including — but not limited to — resizing, scaling, adjusting, cropping, stylizing, filtering, watermarking, and face detection.

This document provides developers with information on how to integrate with the Pixaven 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.

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.pixaven.com/1.0/account to test your credentials for validity.

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

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

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 Pixaven 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.

Input image formats:JPEGJPEG2000PNGAnimated PNGGIFAnimated GIFWebPHEICTIFFBMPICOPSDSVG
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.

Alternately you can choose to instruct the API to send a Webhook to your endpoint of choice with the JSON response. That way you can defer parsing the response from the Pixaven API or even have a dedicated application only for that purpose. You can also query delivered Webhooks programmatically.

Binary Responses

The Pixaven 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": "https://dl.pixaven.com/50/59/66/3f/e7b6-418d-a4cd-af0a7e478134/image.jpg"
}

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

Using External Storage Providers

The Pixaven 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 Pixaven 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.

HTTP/1.1 429 TOO MANY REQUESTS

Date: {{now}}
Status: 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 Pixaven 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": "Adjust 'contrast' parameter must be an integer within -100 to 100 range"
}

We use both proprietary and third-party cookies to improve your browsing experience and to provide you with a better service. By continuing to use this site you consent our use of cookies as described in our Cookie Policy×