API Reference

The Abraia API REST is built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. It uses resource-oriented URLs and HTTP codes to indicate API errors, and JSON is returned by most of API responses, although our API libraries convert responses to appropriate language-specific objects. There are three libraries available for seamless API integration:

Introduction

There are three main endpoints to handle the API in https://api.abraia.me:

  • The files endpoint (https://api.abraia.me/files/) handles files.
  • The images endpoint (https://api.abraia.me/images/) handles image transformations.
  • The videos endpoint (https://api.abraia.me/videos/) handles video transformations.

Authentication

Authentication is performed with API Keys via HTTP Basic Auth. Provide your API Key as the basic auth username value and the API Secret as the password value. You can manage your API keys in the console.

Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Example request:

curl -u apiKey:apiSecret https://api.abraia.me/files/

curl uses the -u flag to pass basic auth credentials (user:password).

To test request you must use your account API keys, replacing apiKey and apiSecret with your actual API keys. Curl uses the -u flag to pass basic auth credentials (apiKey:apiSecret).

Files storage

List files

Retrieve information about all the files stored in a cloud folder using the following URL:

GET /files/{userid}/

This endpoint retrieves all the file data as a JSON structure with a list of files and folders.

Example

curl -u apiKey:apiSecret https://api.abraia.me/files/demo/

The above command returns JSON structured like this:

{
   "files": [
      {
         "date": 1513537440.0,
         "md5": "9f1f07e9884c4b11b048614561eebd89",
         "name": "random_97.jpg",
         "size": 112594,
         "source": "demo/random_97.jpg",
         "thumbnail": "demo/tb_random_97.jpg"
      },
      {
         "date": 1513533727.0,
         "md5": "7ac57ee27b4474c7109e3c643948a9de",
         "name": "random_96.jpg",
         "size": 70232,
         "source": "demo/random_96.jpg",
         "thumbnail": "demo/tb_random_96.jpg"
      }
   ],
   "folders": [
      {
         "name": "videos",
         "source":"demo/videos/"
      }
   ]
}

Upload file

Upload a local or a remote file using the following URL:

POST /files/{userid}/{path}

This URL creates the resource on the cloud and returns the signed URL to upload the file.

A JSON object specifies the name and type of the file or the remote url.

Example

curl -u apiKey:apiSecret -X POST -d '{"name": "tiger.jpg", "type": "image/jpeg"}' https://api.abraia.me/files/userid/

The above command returns JSON structured with the upload URL like this:

{
   "uploadURL": "https://s3.eu-west-1.amazonaws.com/store.abraia.me/demo/tiger.jpg?AWSAccessKeyId=ASIAWYD4NR3V2Q3QGRHM&Content-Type=image%2Fjpeg&Expires=1539444387&Signature=PtC917pbwI33Yy%2BHLvCRUquW3Z4%3D&x-amz-security-token=FQoGZXIvYXdzEPn%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDAydZFATwU34O1CCNCLvAaQESCzuGMJjBdvp6A5rLvlfGN%2BlvdqUoTm52fwBH0Pjaf3Pq7bD2gNXk34RvbRCrG1GKMyq6nEDiMuzReJdl%2F4R7uMLhr2es%2FcvvHqYqopgsYpIwQRqVfEOCi9uxuLwOmbiuDl137QkTG9LcxnI4qc%2BswakShQZkdZ1RtkJrWluWfl0qN6LVMvDVIhFb74%2BWojy8asgw%2BvtNRV%2FAv9aaCPUjzNGmsmd%2FuLU9Vc%2Fsj0CSOns%2BD3%2BQmFKPGz5D6P4ihWqxfqhzm4i23Oq93XfiGqgrA%2FKMPNP06zfL%2F3qVpJLHZRhnkJRv27jObGVa0GoKJ2WiN4F"
}

This uploadURL needs to be used to upload the file data.

curl -H 'Content-Type: image/jpeg' -T tiger.jpg 'ttps://s3.eu-west-1.amazonaws.com/store.abraia.me/demo/tiger.jpg?AWSAccessKeyId=ASIAWYD4NR3V2Q3QGRHM&Content-Type=image%2Fjpeg&Expires=1539444387&Signature=PtC917pbwI33Yy%2BHLvCRUquW3Z4%3D&x-amz-security-token=FQoGZXIvYXdzEPn%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDAydZFATwU34O1CCNCLvAaQESCzuGMJjBdvp6A5rLvlfGN%2BlvdqUoTm52fwBH0Pjaf3Pq7bD2gNXk34RvbRCrG1GKMyq6nEDiMuzReJdl%2F4R7uMLhr2es%2FcvvHqYqopgsYpIwQRqVfEOCi9uxuLwOmbiuDl137QkTG9LcxnI4qc%2BswakShQZkdZ1RtkJrWluWfl0qN6LVMvDVIhFb74%2BWojy8asgw%2BvtNRV%2FAv9aaCPUjzNGmsmd%2FuLU9Vc%2Fsj0CSOns%2BD3%2BQmFKPGz5D6P4ihWqxfqhzm4i23Oq93XfiGqgrA%2FKMPNP06zfL%2F3qVpJLHZRhnkJRv27jObGVa0GoKJ2WiN4F'

It is also possible to upload a remote URL. For instance, an image of Usain Bolt from wikimedia.

Usain Bolt from Wikimedia Commons

curl -u apiKey:apiSecret -X POST -d '{"url": "http://upload.wikimedia.org/wikipedia/commons/1/13/Usain_Bolt_16082009_Berlin.JPG"}' https://api.abraia.me/files/userid/

Download file

Retrieve an stored file using the following URL:

GET /files/{userid}/{path}

Replace {userid} and {path} with your user id and file path. The API call will return an 307 status code with the signed URL redirection to download the file data.

Example

curl -u apiKey:apiSecret -L https://api.abraia.me/files/demo/bird.jpg -o bird.jpg

Delete file

Delete a stored resource specified by its path.

DELETE /files/{userid}/{path}

Move file

Move a stored file from an oldPath to a newPath using the following URL:

POST /files/{newPath}

This URL creates the new resource from the one specified in the JSON object with the store parameter.

Example

curl -u apiKey:apiSecret -X POST -d '{"store": "demo/bird.jpg"}' https://api.abraia.me/files/demo/test/bird.jpg

The above command returns a response as bellow:

{
  "file": {
    "name": "bird.jpg",
    "source": "demo/test/bird.jpg"
  }
}

Image transformation

The image transformation API provides powerful algorithms to achieve the best quality results resizing and optimizing images, in order to adapt them to the graphic design of your website or mobile application.

To retrieve an optimized image is as simple as using the following URL:

GET /images/{userid}/{path}?q=auto

Replace {userid} and {path} with the image path and filename, and the API call will transform the image on-the-fly to return the optimized result. We chose and optimize every compression parameter to provide the best result based on the perceptive analysis of the original image.

Query parameters

Query parameters are used to specify image transformations.

Parameter Description
w (optional) Image width
h (optional) Image height
q (optional) Image quality
m (optional) Resize and crop mode (auto, crop, face, thumb, resize)
fmt (optional) Image format (jpeg, png, gif, webp)

Examples

To optimize and resize an image maintaining the aspect ratio is enough to specify the width (w) or the height (h) of the new image. w=500 sets the width of the image to 500 pixels and maintains the aspect ratio of the image adapting the height.

curl -u apiKey:apiSecret https://api.abraia.me/images/demo/Usain_Bolt_16082009_Berlin.JPG?w=500 -o UsainBolt.jpg

Usain Bolt from Wikimedia Commons Resized to width 500

To adapt the image to the required aspect ratio is enough to specify the width and height parameters. w=500&h=500 sets the width and the height to 500 pixels changing the aspect ratio to 1:1, automatically selecting the best cropping area.

curl -u apiKey:apiSecret https://api.abraia.me/images/demo/Usain_Bolt_16082009_Berlin.JPG?w=500&h=500 -o UsainBolt.jpg

Usain Bolt from Wikimedia Commons Smartly Cropped to 500x500

Image transformations

flowers resize width

Parameters: w=300

Description: Resizes the image maintaining the aspect ratio.


flowers resize height

Parameters: h=192

Description: Resizes the image maintaining the aspect ratio.


flowers forced crop

Parameters: w=300&h=192&m=crop

Description: Forces the crop of the image when the aspect ratio is the original one.


flowers smart crop

Parameters: w=300&h=300

Description: Smartly crops and resize the image to adopt the new aspect ratio.


flowers forces resize

Parameters: w=300&h=300&m=resize

Description: Forces the resize of the image when the aspect ratio is different from the one in the original image.


flowers resize aspect ratio

Parameters: w=300&ar=1:1 or h=300&ar=1

Description: Smartly crops and resize the image to adopt the new aspect ratio.


flowers resize aspect ratio

Parameters: w=300&ar=1.5

Description: Smartly crops and resize the image to adopt the new aspect ratio.


flowers resize dpr

Parameters: w=150&ar=1.5&dpr=2

Description: Adapts the image for retina displays, adopting the specified device pixel ratio (1, 2, 3).


flowers quality

Parameters: w=300&ar=1.5&q=50

Description: Sets the quality of the delivered jpg or webp image to 50 in the range (1, 100) - 1 is the lowest quality and 100 is the highest.

Enhancement filters

building wall house architecture original

Original building wall house image

house color balanced

Parameters: f=cbalance

Description: Applies a simplest color balance..


house intensity balanced

Parameters: f=ibalance

Description: Applies a simplest intensity balance.


house tone mapped

Parameters: f=retinex

Description: Applies a retinex tone mapping.


house sharpen

Parameters: f=sharpen

Description: Applies a sharpen filter to the image.

Filter effects

beach bungalow original

Original beach bungalow image

beach blur filter

Parameters: f=blur

Description: Applies a Gaussian blur filter to the image.


beach pixelate filter

Parameters: f=pixelate

Description: Applies a pixelizer filter to the image.


beach grayscale filter

Parameters: f=grayscale

Description: Converts the image to grayscale.


beach desaturate filter

Parameters: f=desaturate

Description: Desaturates the image.


beach brighten filter

Parameters: f=brighten

Description: Applies a brighten effect to the image.


beach contrast filter

Parameters: f=contrast

Description: Applies a contrast effect to the image.

beach sepia filter

Parameters: f=sepia

Description: Applies a sepia effect.


beach sunlight filter

Parameters: f=sunlight

Description: Applies a sunlight effect to the image.


beach lumo filter

Parameters: f=lumo

Description: Applies a lumo effect to the image.


beach country filter

Parameters: f=country

Description: Applies a country effect to the image.

beach cartoonify filter

Parameters: f=cartoonify

Description: Applies a cartoonify effect to the image.


beach sketch filter

Parameters: f=sketch

Description: Applies a sketch effect to the image.

beach crossprocess filter

Parameters: f=crossprocess

Description: Applies the crossprocess film effect filter.


beach velviaesque filter

Parameters: f=velviaesque

Description: Applies the velviaesque film effect filter.


beach proviaesque filter

Parameters: f=proviaesque

Description: Applies the proviaesque film effect filter.


beach portraesque filter

Parameters: f=portraesque

Description: Applies the portraesque film effect filter.

Action filters

Actions are an experimental feature to provide a powerful content-based edition tool. They are going to be developed to enable smart actions like adaptive watermarking. For instance, changing the text color based on the background color, or using the negative space to place the watermark.

anonymized couple picture

Parameters: atn=blur-faces

Description: Anonymize pictures using Abraia's face detection feature.


meme action example

Parameters: atn=meme&txt1=Hello!&fmt=jpg&txt2=Bye!

Description: Action to easily create MEMES.


Video transcoding

Run a video transcoding task using the following URL:

GET /videos/{userid}/{path}?fmt=mp4

Replace {userid} and {path} with the video path. The API call returns the new video path.

Query parameters

Parameter Description
fmt (required) Video format
w (optional) Video width
h (optional) Video height
m (optional) Resize and crop mode (pad, crop, blur)

Example

curl -u apiKey:apiSecret https://api.abraia.me/videos/demo/videos/zara.mp4?fmt=mp4&w=600

The above command returns JSON structured like this:

{
   "path": "demo/videos/zara/zara_600.mp4"
}

Errors

Abraia uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a not found resource, etc.), and codes in the 5xx range indicate an error with Abraia's servers (these are rare).

HTTP status code summary

Code Status Description
200 OK. Successful Everything worked as expected.
201 Created A new resource was successfully created.
307 Temporal Redirect The resource requested has been temporarily moved to the URL given by the Location headers.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
402 Payment Required No credits available.
403 Not allowed The service is not available for your account.
404 Not Found The resource requested does not exist.
500 Server Error Something went wrong on the service.