Introduction

The iLoveIMG API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

To start developing, we provide you a Free Account. However this account is limited to a few hundreds of processing files per month, if you need more, you can acquire more files from our pricing page.

Quick Start

This Reference is for developers who pretend to create their own API library or for those who don't find their preferred library in our library compatibility list. The quickest way to start using our API is:

  • Register as developer.
  • Get a Project ID and its related Secret Key.
  • Download one of our API Libraries.
  • Try out our demos in the API Library.
  • And, of course, read this documentation!

If you have any kind of suggestion about this documentation or about the API, please don’t hesitate to contact us.

Request workflow

The image processing workflow with iLoveIMG API is very simple and consists of 4 basic request instructions: Start task, Upload files, Process files and Download files. Once the API have executed this four steps, you should have your image files processed with your desired tool and downloaded anywhere you like.

Below you will see a complete reference to these 4 requests and the parameters of each step.

Authentication

We are using a very simple but effective Authentication method: JWT, JSON Web Tokens. It consist in sending a Bearer Header in every request with signed token by your Secret Key provided in your iLoveIMG API Developer Account. Your Secret Key may never be exposed, but the signed token can be exposed and you must send it in every header request parameter Authorization: Bearer {signed_token} . All the signed tokens must have no more of 2 hour expiration. All our API Libraries manage the authentication automatically. You only need to set your Private Key and your Public Key in the API Library.

If you are developing your own library/requests there are two methods of getting the signed token. One method is by self signing it (recommended for server side code) and the other is by requesting it to our Authentication server (recommended for client side code).

Self signed token

You must use your secret and public key pair to generate the signed token to send in to the Authorization: Bearer {signed_token} header of every request You can find the JWT libraries directly on the JWT official website. Remember: the claims 'exp', 'nbf' and 'iat' must be in UTC timezone.

Request signed token to our Authentication server

Requesting to the /auth resource you will get as a response the token to use in your Authorization: Bearer {signed_token} that you'll send in every request (/start, /upload, /process, /download). We strongly recommend to activate filters by domain and IP if you need to request the token from our /auth server so only the requests made from the domains you set will be accepted. Remember that the token has an expiration date and must be requested again.


POST https://api.iloveimg.com/v1/auth

public_key
string
REQUIRED
Project public ID you can find on 'My Projects'

Start

Retrieve the information of which server will be your assigned server and the Task ID to use. The request must contain the tool you want to access.

Get Server & Task ID

GET https://api.iloveimg.com/v1/start/{tool}

Upload

This is the second step of the Task. Here is where you upload your files for a given task. The files will be uploaded and stored in the server until the order of process will be sent (Step 3 of a Task).

It accepts chunk file upload. When uploading a chunk file, if the last chunk is sent and some of the previous chunks are missing it will throw an error. Finally, files can be upload either from local or web source.

Upload file

POST https://{server}/v1/upload

task
string
REQUIRED
Task ID where the files must be uploaded
SOURCE FILE IS LOCAL
file
file
OPTIONAL
File to be uploaded.
chunk
integer
OPTIONAL
If is a chunk upload this number indicate the number of chunk being uploaded. Always send the chunks in order. First chunk must be 0.
chunks
integer
OPTIONAL
If is a chunk upload this number indicate the total number of chunks for this file.
SOURCE FILE IS FROM CLOUD
Instead of uploading the file from local storage, the iLoveIMG API allows you to upload files from an URL.
cloud_file
string
OPTIONAL
The public URL of the file to be uploaded (will be downloaded directly by the server API).

Remove an already uploaded file from server

POST https://{server}/v1/upload/delete

task
string
REQUIRED
Task ID
server_filename
string
REQUIRED
The file to be removed on the server.

Process

Once uploaded the files for the Task this resource initiate the processing of all files. In the request you must specify which files to process of the uploaded ones in the Step 2 (Upload). That means that you can send the order to process less files than the uploaded ones. If some file has an error while processing check the table of File Status Types to know all statuses.

When sending the request is you must wait until the process finished. If you don't want to wait you can use the webhook parameter.

Process files

POST https://{server}/v1/process

task
string
REQUIRED
Task ID to be processed
tool
string
REQUIRED
Accepted values: resizeimage, cropimage, compressimage, convertimage, watermarkimage, repairimage, rotateimage
files
array
REQUIRED
Files to process. The order of the array will be the order that files will be processed. Files has the following attributes:

[server_filename]
string
REQUIRED
Server file name
[filename]
string
REQUIRED
Original filename of the file to process.
[rotate]
integer
OPTIONAL
Accepted values: 0,90,180,270
Default: 0
ignore_errors
boolean
OPTIONAL
Force process although some of the files to process are damaged or throw an error. If damaged/error files are equal to total files to process this value does not take effect. On successful reponse all error files will be listed as warnings. Values: true, false
Default: true
output_filename
string
OPTIONAL
{date}=current date, {n}=file number, {filename}=original filename, {tool}=the current processing action. Example: file_{n}_{date}
packaged_filename
string
OPTIONAL
If output files are more than one will be served compressed. Specify the filename of the compressed file. {date}=current date, {n}=file number,{filename}=original filename, {app}=the current processing action. Example: zipped_{n}_{date}
Default:output
file_encryption_key
string
OPTIONAL
If specified it is assumed all previously uploaded files for the task has been uploaded encrypted. The key will be used to decrypt the files before processing and re-encrypt them after processing. Only keys of sizes 16, 24 or 32 are supported.
Default: null
try_image_repair
boolean
OPTIONAL
When a image to process fails we try to repair it automatically.
Default: true
custom_int
integer
OPTIONAL
Use this parameter to store integers as you wish. You can use it to filter your tasks in the GET /task resource.
Default: null
custom_string
string
OPTIONAL
Use this parameter to store the strings as you wish. It can't be used to filter tasks in GET /task resource.
Default: null
webhook
string
OPTIONAL
Callback URL. If you don't want to maintain the connection opened until the task processing finishes send webhook equal an valid URL. The API will close immediately the connection and will POST all the /task resource information to the URL provided. Optionally this parameter can be equal to void (string). When equal void the behaviour will be the same but no callback will be sent, this is useful if you don't want to wait the process to end or receive callbacks giving you the freedom of send periodic GET calls to /task/{task} to know the status of that task and if it has been completed.
Default: null
SPECIFIC TOOL PARAMETERS
List of parameters for every tool that supports custom configurations. If a tool isn't listed below, means that tool has no custom parameters (but still exists!).
RESIZE IMAGE
resize_mode
string
OPTIONAL
Choose resize mode.
  • pixels: the resize will be set using pixels.
  • percentage: the resize will be set as a percent.
Default: pixels
pixels_width
integer
OPTIONAL
The width, in pixels of the resized. Required if resize_mode is set to pixels
Default: null
pixels_height
integer
OPTIONAL
The height, in pixels of the resized. Required if resize_mode is set to pixels
Default: null
percentage
integer
OPTIONAL
The percent value to resize.
Default: null
maintain_ratio
boolean
OPTIONAL
If set as true, resize will keep aspect ratio and images will not be distort.
Default: true
no_enlarge_if_smaller
boolean
OPTIONAL
Controls if the image can be gigger than the original on resize.
Default: true
CROP IMAGE
x
integer
OPTIONAL
The horizontal point where start to crop
Default: 0
y
integer
OPTIONAL
The vertical point where start to crop
Default: 0
width
integer
REQUIRED
The width, in pixels of the area to crop.
height
integer
REQUIRED
The height, in pixels of the area to crop.
COMPRESS IMAGE
compression_level
string
OPTIONAL
Compression level. Accepted values: extreme=Extreme compression, recommended=Recommended compression, low=Low compression
Default: recommended
CONVERT IMAGE
to
string
OPTIONAL
The format to convert to. Accepted values are jpg, png, gif, gif_animation. Convert to jpg can be (almost) from any image fromat. Convert to png and gif can be only from jpg images.
Default: jpg.
gif_time
integer
OPTIONAL
Only for gif_animation, define the seconds per image, in hundredths of a second.
Default: 50
gif_loop
boolean
OPTIONAL
Set if animation stops at the end or loops forever
Default: true
ROTATE IMAGE
Rotate tool has no options, just set rotation in file.
WATERMARK IMAGE
elements
array
REQUIRED
An array of elements to stamp. This means you can set multiple elements to stamp.

['type']
string
OPTIONAL
The type for the element. Element can be image or text.
Default: text.
[text]
string
OPTIONAL
The text to stamp if type is text.
[image]
string
OPTIONAL
The image to stamp if element type is image. The stamp image must be uploaded in the /upload resource. This image parameter must referer to the server_filename (JPG or PNG) to stamp in the PDF.
[gravity]
string
OPTIONAL
Accepted values: North, NorthEast, NorthWest, Center, CenterEast, CenterWest, East, West, South, SouthEast, SouthWest.
Default: Center.
[vertical_adjustment_percent]
integer
OPTIONAL
Adjust how much space must modify the position of the position defined in gravity, based on a percent of the base image, it accepts positive and negative values.
[horizontal_adjustment_percent]
integer
OPTIONAL
Adjust how much space must modify the position of the position defined in horizontal_position, based on a percent of the base image, it accepts positive and negative values.
[rotation]
integer
OPTIONAL
Angle of rotation. Accepted integer range: 0-360.
Default: 0.
[font_family]
string
OPTIONAL
Accepted values: Arial, Arial Unicode MS, Verdana, Courier, Times New Roman, Comic Sans MS, WenQuanYi Zen Hei, Lohit Marathi.
Check our guide for Fonts
Default: Arial Unicode MS.
[font_style]
string
OPTIONAL
Accepted values: null (Regular/Normal), Bold, Italic, Bold-Italic.
Check our guide for Fonts
Default: null.
[font_size]
integer
OPTIONAL
Default: 14.
[font_color]
string
OPTIONAL
Hexadecimal color.
Default: #000000.
[transparency]
integer
OPTIONAL
Percentage of opacity for stamping text or image. Accepted integer range 1-100.
Default: 100.
[mosaic]
boolean
OPTIONAL
If true, this value overrides all position parameters and stamps the image or text 9 times per page (one for each gravity position).
Default: false.
REPAIR IMAGE
Repair tool has no options.
FILE STATUS TYPES
FileSuccess
This file has been processed successfully.
FileWaiting
This file is waiting to be processed.
WrongPassword
This file has not been processed because needed a password and was not provided or incorrect.
TimeOut
This file has not been processed correctly because it took more than your time limit to process it.
ServerFileNotFound
This file has not been processed because has not been found in the server.
DamagedFile
This file has not been processed because it was damaged or we were unable to read it.
NoImages
This file has not been processed because we couldn't find any images to extract. Maybe there are vectors?
OutOfRange
This file has not been processed because some of the ranges do not match the number of pages.
UnknowError
Unknow Error.


Download

Download the output files for the given Task. If the output file is only one it is served the output file directly. If is more than one file these are served in a compressed ZIP folder. If the processed files are more than one and there are multiple output files for every processed file, the ZIP will contain a folder for every processed file.

Download output files

GET https://{server}/v1/download/{task}

Task

The /task/{task} resource give information about a task status. If the task is TaskSuccess, TaskSuccessWithWarnings or TaskError it will also specify all files of the Task and their status one by one.

Get a Task details

GET https://api.iloveimg.com/v1/task/{task}


For security reasons the next resource /task can be accessed only by server side code and providing your secret_key as a parameter aswell.

List and filter all Tasks

POST https://api.iloveimg.com/v1/task

secret_key
string
REQUIRED
Your project secret key.
page
integer
OPTIONAL
Results are offered paginated in 50 results per page.
Default: 1
tool
string
OPTIONAL
Filter tasks by tool.
Default: null
status
string
OPTIONAL
Filter tasks by task status type, for instance TaskSuccess.
Default: null
custom_int
integer
OPTIONAL
Filter tasks by custom_int.
Default: null

All Tasks and their related files are deleted after one hour of being processed. But if is needed to delete the task and all related files immediately you can by sending a DELETE request to /task.

When deleting a Task you'll get the TaskDeleted status in the response but if the its previous status was TaskWaiting the response will contain a UploadDeleted and if called again it will throw an error TaskNotFound in the following requests.

Delete a Task

DELETE https://{server}/v1/task/{task}

If you need to apply different tools on the same files, connected task resource will allows you to execute a new task on the files resulting from the previous tool. Using this resource you don't need to upload your files again.

The response will contain the new task id and the files (the server_filename as key and filename as value), with server filename and the file name, you will need for the process step.

Once the new connected task is created you can add, remove files, and work like another tool.

Connected task

POST https://api.iloveimg.com/v1/task/next

task
string
REQUIRED
The parent task id.
tool
string
REQUIRED
The tool for the next task.

Security

As an API user you will only have access to your tasks and files. The original and processed files are deleted after an hour (depending on your tier can be more). After processing and downloading the output files you can also remove the task and the files inherit.

Rate Limiting

All endpoints are subject to API rate limiting depending on the tier. As part of every response, the HTTP headers will show your current rate limit status.

File Encryption

The files are always transmitted encrypted via SSL but in addition the iLoveIMG API offer also another layer of security: store in our servers your files always encrypted. The only moment when the file will be unencrypted is while processing it. For this encryption and decryption you must add to your JWT signature the file_encryption_key claim on the JWT Payload data. The value of file_encryption_key must be a string of 16, 24 or 32 chars. That means that nobody can have access to your files without knowing your File Encryption Key. The File Encryption Key must be the same for same task.

Open task limitation

There is a limitation to tasks that can be opened about 10% of your monthly file limits subscription. If you reach this limit of opened tasks an error will be sent warning you to close tasks (by process or destroy them). Note that a task is opened since an Upload is made until Process is executed with the exception of password protected files; in this case task will be closed when Process can be done with a right password.

IP and domain filtering

Depending on the tier you have you can configure from where your API request must be allowed. All API requests coming from other domains or IP that are not configured will be rejected.

Errors

iLoveIMG API 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 processing failed, etc.), and codes in the 5xx range indicate an error with iLoveIMG's servers. All error responses have the same structure, and in the param you'll find specified the arguments and errors.

For ProcessingError in the param you'll expect an Array of failed files and the reason of failure. When error is a 400 Bad request we can specify which type of error we are giving (see the right table).

HTTP Error codes

type
The type of error returned. Can be: HTTP Error, UploadError, ProcessingError, DownloadError.
message
optional
A human-readable message providing more details about the error.
code
optional
HTTP Error code.
param
optional
The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.

HTTP Error Response Codes

200 - OK
Everything worked as expected.
400 - Bad Request
The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized
No valid API key provided or not correct.
404 - Not found
The requested resource doesn't exist.
429 - Too many requests
Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
5xx - Server Errors
Something went wrong on our API's end
ERROR 400 TYPES
UploadError
Some parameter or the file is missed in the request or something went wrong.
ProcessingError
Some parameter is missed in the request or the process was unsuccessful.
DownloadError
The file may have been already removed or expired.

Testing

Debug parameter

Any resource can be called with an additional parameter debug. When sending the debug parameter equal true the resource won't process the request but it will output the parameters received by the server.

Fonts compatibility

For tools like Watermark Image which allows to set a font family for its content, there are a list of compatible fonts to use with any alphabet. Take into account that any use of a font no set on this list could cause spelling issues.

Latin, Cirillic and Greek alphabets

Arial (Regular, Bold, Italic, Bold Italic)
Courier (Regular, Bold, Italic, Bold Italic)
Times New Roman (Regular, Bold, Italic, Bold Italic)
Verdana (Regular, Bold, Italic, Bold Italic)
Comic Sans MS (Regular, Bold)

Arabic alphabet

Arial (Regular)
Courier (Regular)
Times New Roman (Regular)

Chinese, Japanese and Korean alphabets

WenQuanYi Zen Hei (Regular)
Arial Unicode MS (Regular)

Hindi alphabets

Lohit Marathi (Regular) Lohit Devanagari (Regular)