Log in Sign up

Api reference

Introduction

The iLoveIMG API is organized around the REST standard, having a predictable resource-oriented URLs through HTTP methods where obtain the information in JSON format.


We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side. Although you should never expose your secret API key in the client-side code.


To start developing, register to iLoveIMG Developers and you will be provided with a free account. This account comes with a free 250 files limit to process each month. However, if you need more, you can acquire more files from our Pricing page.


Before we begin, we recommend that you import our Postman Collection & Environment from the table on the right and use it as a playground. If you are logged in, the last active project credentials will automatically appear inside the environment. Remember to select the environment before calling any request from the collection.

Libraries
PHP
Postman

Quick Start

This Reference is for developers who wish 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 to:

  • Register as a developer.
  • Get a Project ID and its related Secret Key from the API Keys section of your console.
  • Download one of our API Libraries.
  • Try out our demos in the API Library.
  • Lastly, remember to read this documentation!

If you have any comments or suggestions for this documentation or 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 has executed these four steps, your image files will have been processed with your desired tool and downloaded anywhere you like.


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

Workflow diagram

Authentication

We are using a very simple but effective Authentication method: JWT, JSON Web Tokens. It consists of sending a Bearer Header in every request with a 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}. Take into account that all signed tokens expire after 2 hours. 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 for 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 from our authentication server

When you send a request to the /auth resource, you will receive the token to use in your Authorization: Bearer {signed_token} that you'll send in every request (/start, /upload, /process, /download). We strongly recommend that you activate filters by domain and IP if you need to request the token from our /auth server. This way, 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.

Authenticate
https://api.iloveimg.com/v1/auth
public_key
string
Project public key that you can find in admin panel.
Response

Main resources

Start

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

Get Server & Task ID
https://api.iloveimg.com/v1/start/{tool}
Response

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 process order is 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 uploaded either from local or web sources.

Upload file
https://{server}/v1/upload
task
string
Task ID where the files must be uploaded.
Source file is local
file
File
File to be uploaded.
chunk
integer
If it is a chunk upload this number indicates the number of chunks being uploaded. Always send the chunks in order. First chunk must be 0.
chunks
integer
If it is a chunk upload this number indicates the total number of chunks for this file.
Source file is from the cloud
cloud_file
string
Public URL of the file.
Remove an already uploaded file from server
https://{server}/v1/upload/{task}/{server_filename}
Response

Process

Once the files are uploaded for the Task, this resource initiates the processing of all files. In the request, you must specify which files you want to process from the uploaded ones in Step 2 (Upload). This means that you can request to process fewer files than the uploaded ones. If some files have an error while processing, you can check their status in the table of File Status Types. If the error is WrongPassword the response will throw a 400 error. However, the Task Status would be kept as TaskWaiting so you can try to resend the request to process files using the required passwords.


When sending the request, you need to wait until the process is finished. However, if you don't want to wait, you can use the webhook parameter.

Process files
https://{server}/v1/process
task
string
Task ID to be processed.
tool
string
Accepted values: resizeimage, cropimage, compressimage, convertimage, watermarkimage, repairimage and rotateimage.
files
array
Files to process. The order of the array will be the order that files will be processed. The files has the following attributes:
server_filename
string
Server file name.
filename
string
Original filename of the file to process.
rotate
integer
Rotation to apply before process. Accepted values: 0, 90, 180, 270.
0
password
string
Password to open the file in case of having one.
ignore_errors
boolean
Force process although some of the files 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 response, all files with errors will be listed as warnings. Values: true, false.
true
output_filename
string
{date}=current date, {n}=file number, {filename}=original filename, {tool}=the current processing action. Example: file_{n}_{date}.
packaged_filename
string
If there are more than one output files, they will be compressed into a ZIP file. Specify the filename of the compressed file. {date}=current date, {n}=file number, {filename}=original filename, {tool}=the current processing action. Example: file_{n}_{date}.
output
file_encryption_key
string
If specified, all previously uploaded files for the task will be uploaded encrypted. The key will be used to decrypt the files before processing and re-encrypt them after processing. Only key sizes of 16, 24 or 32 characters are supported.
try_image_repair
boolean
When an image file fails to be processed, we try to repair it automatically.
true
custom_int
integer
Use this parameter to store integers as you wish. You can use it to filter your tasks in the GET /task resource.
custom_string
string
Use this parameter to store integers as you wish. You can use it to filter your tasks in the GET /task resource.
webhook
string
Callback URL. If you don't want to maintain the connection open until the task processing is finished, send webhook equal and a valid URL. The API will close the connection immediately and will POST all the /task resource information to the URL provided. Optionally this parameter can be equal to empty string. When is equal to empty string, 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.
Resize extra parameters
resize_mode
string

Choose the resize mode. Accepted values:

  • pixels: the resize will be set using pixels.
  • percentage: the resize will be set as a percentage of the original image.
pixels
pixels_width
integer
If resize_mode is pixels
The width in pixels of the resized image.
pixels_height
integer
If resize_mode is pixels
The height in pixels of the resized image.
percentage
integer
If resize_mode is percentage
The percentage value to resize.
maintain_ratio
boolean
If set as true, resize will keep aspect ratio and images will not be distort.
true
no_enlarge_if_smaller
boolean
Controls if the image can be gigger than the original on resize.
true
Crop extra parameters
width
integer
The width in pixels of the area to crop.
height
integer
The height in pixels of the area to crop.
x
integer
The horizontal point where start to crop.
0
y
integer
The vertical point where start to crop.
0
Compress extra parameters
compression_level
string
Compression level. Accepted values: extreme=Extreme compression, recommended=Recommended compression, low=Low compression.
recommended
Convert extra parameters
to
string
The format to convert to. Accepted values are jpg, png, gif and gif_animation (static or animated). Convert to jpg can be (almost) from any image format. Convert to png and gif can be only from jpg images.
jpg
gif_time
integer
if to is gif_animated
Only for gif_animation, define the seconds per image, in hundredths of a second.
50
gif_loop
integer
if to is gif_animated
Set if animation stops at the end or loops forever.
true
Watermark extra parameters
elements
array
An array of elements to stamp. This means you can set multiple elements to stamp.
type
string
The type for the element. Accepted values: image or text.
text
text
string
if type is text
The text to stamp
image
string
if 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).
gravity
string
Accepted values: North, NorthEast, NorthWest, Center, CenterEast, CenterWest, East, West, South, SouthEast, SouthWest.
Center
vertical_adjustment_percent
integer
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.
0
horizontal_adjustment_percent
integer
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.
0
rotation
integer
Angle of rotation. Accepted integer range: 0-360.
0
font_family
string
Accepted values: Arial, Arial Unicode MS, Verdana, Courier, Times New Roman, Comic Sans MS, WenQuanYi Zen Hei, Lohit Marathi.
0
font_style
string
Accepted values: null (Regular/Normal), Bold, Italic.
null
font_size
integer
14
font_color
string
Hexadecimal color.
#000000
transparency
integer
Percentage of opacity for stamping text or image. Accepted integer range 1-100.
100
mosaic
boolean
If true, this value overrides all position parameters and stamps the image or text 9 times per page.
false
Rotate extra parameters

Rotate tool has no options, just set rotation property in file.

Repair extra parameters

Repair tool has no options.

Response
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.
UnknownError
Unknown Error.

Download

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

Download output files
https://{server}/v1/download/{task}
Response

Other resources

Task

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

Get a task details
https://api.iloveimg.com/v1/task/{task}

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

List and filter all tasks
https://api.iloveimg.com/v1/task
secret_key
string
Your project secret key.
page
integer
Results are offered paginated in 50 results per page.
1
tool
string
Filter tasks by tool.
status
string
Filter tasks by task status type, for example TaskSuccess.
custom_int
integer
Filter tasks by custom_int.

All tasks and their related files are deleted after two hours of being processed. However, if you need to delete the task and all related files immediately, you can do so by sending a DELETE request to /task.


When deleting a task, you'll get the TaskDeleted status in the response, but if the previous status was TaskWaiting the response will contain a UploadDeleted. If called again, it will throw the error TaskNotFound in the following requests:

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

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


The response will contain the new task ID and the files as an array of objects where the key is the server_filename and filename is the value. You will need this information for the process step.


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

Connect task
https://{server}/v1/task/next
task
string
The parent task id.
tool
string
The tool for the next task.
Task status types
TaskWaiting Files for the task have been uploaded but processing order has not been received yet
TaskProcessing The task is currently processing files.
TaskSuccess The task has already been processed successfully.
TaskSuccessWithWarnings The task has already been processed successfully with warnings.
TaskError The task has been processed unsuccessfully.
TaskDeleted The task has already been deleted.
TaskNotFound Task not found.

Topics

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, it can be more). After processing and downloading the output files you can also remove the task and the files involved in the process.

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 also offers another layer of security: store your files in our servers 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

The number of tasks that can be opened at one time is limited to 10% of your monthly subscription’s file limits. If you reach this limit of opened tasks, an error will be sent warning you to close tasks (by processing or destroying them). Note that a task is opened from the moment an Upload is made until the Process is executed, with the exception of password-protected files; in this case, the task will be closed when the Process can be completed with a correct 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 due to the information provided (e.g. a required parameter was omitted, a process failed, etc.), and codes in the 5xx range indicate an error with iLoveIMG's servers. All error responses have the same structure, and you’ll find all the arguments and errors specified in the param.


For ProcessingError in the param, you'll expect an Array of failed files and the reason for failure. When the 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 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 already been removed or has 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 such as Add Page Numbers and Add Watermark, which allow you to set a font family for its content, there is a list of compatible fonts to use with any alphabet. Take into account that if you use a font which isn’t on this list, it 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)