Documentation

Image Upload API Reference

This API is organized around REST. Our API has predictable resource-oriented URLs,accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Just Getting Started?

Check out our development quickstart guide.

Authentication

Image Upload API uses API keys to authenticate requests. You can view and manage your API keys in the Accounts page.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All requests made to the API must hold a custom HTTP header named “apikey”. Implementation differs with each programming language. Below are some samples.

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

Endpoints

POST /upload

Upload a file image

Parameters

delay (required)

Specifies whether to introduce a delay in the image optimization process.

Location: Query,Data Type: boolean

upload (required)

The image file that the user wants to upload and optimize.

Location: Body,Data Type: file

background(optional)

Specifies the background color of the image in HEX notation (#f60 or

Location: Query,Data Type: string

callback (optional)

Specifies whether a callback function should be used.

Location: Query,Data Type: boolean

enhance (optional)

Specifies whether image enhancement should be applied.

Location: Query,Data Type: boolean

height(optional)

Specifies the desired height of the image.

Location: Query,Data Type: integer

id_size(optional)

Specifies the size of the ID, which can be an integer or a string.

Location: Query, Data Type: string

lost(optional)

Specifies whether the image can be lost during optimization.

Location: Query, Data Type: boolean

mode_crop(optional)

Specifies the cropping mode for the image.

Location: Query, Data Type: string

option(optional)

Defines an option for image processing.

Location: Query, Data Type: string

quality(optional)

Specifies the desired quality of the image.

Location: Query, Data Type: integer

scale(optional)

Specifies the scale factor for resizing the image.

Location: Query, Data Type: integer

width(optional)

Specifies the desired width of the image.

Location: Query, Data Type: integer

x(optional)

Defines the x-coordinate position of the image.

Location: Query, Data Type: integer

y(optional)

Defines the y-coordinate position of the image.

Location: Query, Data Type: integer

var myHeaders = new Headers();
    myHeaders.append("apikey", "{API-KEY}");
    
    var raw = "{body}";
    
    var requestOptions = {
      method: 'POST',
      redirect: 'follow',
      headers: myHeaders,
      body: raw
    };
    
    fetch("https://api.apilayer.com/image_upload/upload?delay={delay}", requestOptions)
      .then(response => response.text())
      .then(result => console.log(result))
      .catch(error => console.log('error', error));


  import requests

  url = "https://api.apilayer.com/image_upload/upload?delay={delay}"
  
  payload = "{body}".encode("utf-8")
  headers= {
    "apikey": "{API-KEY}"
  }
  
  response = requests.request("POST", url, headers=headers, data = payload)
  
  status_code = response.status_code
  result = response.text


  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api.apilayer.com/image_upload/upload?delay={delay}",
    CURLOPT_HTTPHEADER => array(
      "Content-Type: text/plain",
      "apikey: {API-KEY}"
    ),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS =>"{body}"
  ));
  
  $response = curl_exec($curl);
  
  curl_close($curl);
  echo $response;


  package main

  import (
    "fmt"
    "net/http"
    "io/ioutil"
  )
  
  func main() {
    url := "https://api.apilayer.com/image_upload/upload?delay={delay}"
  
    payload := strings.NewReader("{body}")
  
    client := &http.Client {}
    req, err := http.NewRequest("POST", url, payload)
    req.Header.Set("apikey", "{API-KEY}")
  
    if err != nil {
      fmt.Println(err)
    }
    res, err := client.Do(req)
    if res.Body != nil {
      defer res.Body.Close()
    }
    body, err := ioutil.ReadAll(res.Body)
  
    fmt.Println(string(body))
  }


  import java.io.*;
  import okhttp3.*;
  
  public class main {
    public static void main(String []args) throws IOException{
      OkHttpClient client = new OkHttpClient().newBuilder().build();
  
      MediaType mediaType = MediaType.parse("text/plain");
      RequestBody body = RequestBody.create(mediaType, "{body}");
  
      Request request = new Request.Builder()
        .url("https://api.apilayer.com/image_upload/upload?delay={delay}")
        .addHeader("apikey", "{API-KEY}")
        .method("POST", body})
        .build();
      Response response = client.newCall(request).execute();
      System.out.println(response.body().string());
    }
  }


  require "uri"
  require "net/http"
  
  url = URI("https://api.apilayer.com/image_upload/upload?delay={delay}")
  
  https = Net::HTTP.new(url.host, url.port);
  https.use_ssl = true
  
  request = Net::HTTP::Post.new(url)
  request['apikey'] = "{API-KEY}"
  request.body = "{body}"
  response = https.request(request)
  puts response.read_body


  curl --request POST \
  --url 'https://api.apilayer.com/image_upload/upload?delay={delay}' \
  --header 'apikey: {API-KEY}' \
  --data-raw '{body}'


  var client = new RestClient("https://api.apilayer.com/image_upload/upload?delay={delay}");
  client.Timeout = -1;
  
  var request = new RestRequest(Method.POST);
  request.AddHeader("apikey", "{API-KEY}");
  
  request.AddParameter("text/plain", "{body}",  ParameterType.RequestBody);
  
  IRestResponse response = client.Execute(request);
  Console.WriteLine(response.Content);


  import Foundation

  var semaphore = DispatchSemaphore (value: 0)
  let parameters = "{body}"
  let postData = parameters.data(using: .utf8)
  request.httpMethod = "POST"
  request.httpBody = postData
  
  let url = "https://api.apilayer.com/image_upload/upload?delay={delay}"
  var request = URLRequest(url: URL(string: url)!,timeoutInterval: Double.infinity)
  request.httpMethod = "POST"
  request.addValue("{API-KEY}", forHTTPHeaderField: "apikey")
  
  let task = URLSession.shared.dataTask(with: request) { data, response, error in
    guard let data = data else {
      print(String(describing: error))
      return
    }
    print(String(data: data, encoding: .utf8)!)
    semaphore.signal()
  }
  
  task.resume()
  semaphore.wait()


  CURL *curl;
  CURLcode res;
  curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.apilayer.com/image_upload/upload?delay={delay}");
    curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
    curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");
    struct curl_slist *headers = NULL;
    headers = curl_slist_append(headers, "apikey: {API-KEY}");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  
  const char *data = "{body}";
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
  
    res = curl_easy_perform(curl);
  }
  curl_easy_cleanup(curl);

** A word enclosed with curly brackets “{ }” in the code means that it is a parameter and it should be replaced with your own values when
executing. (also overwriting the curly brackets).

Returns

Below is a sample response from the endpoint


  {
    "height": 1341,
    "image_url": "https://core-production-us-east-1-imageupload.s3.amazonaws.com/0000_372ad59df94349add/7cc4f687_google2.0.0.jpg",
    "name": "google2.0.0.jpg",
    "new_height": 1341,
    "new_width": 2012,
    "optimized_size": 109748,
    "saved_bytes": 130313,
    "size": 240061,
    "success": true,
    "width": 2012
  }

POST /url

Upload an URL image

Parameters

delay (required)

Specifies whether to introduce a delay in the image optimization process.

Location: Query,Data Type: boolean

url (required)

The URL of the image that the user wants to upload and optimize.

Location: Body,Data Type: string

background(optional)

SSpecifies the background color of the image in HEX notation (#f60 or

Location: Query,Data Type: string

callback (optional)

Specifies whether a callback function should be used.

Location: Query,Data Type: boolean

enhance (optional)

Specifies whether image enhancement should be applied.

Location: Query,Data Type: boolean

height(optional)

Specifies the desired height of the image.

Location: Query,Data Type: integer

id_size(optional)

Specifies the size of the ID, which can be an integer or a string.

Location: Query, Data Type: string

lost(optional)

Specifies whether the image can be lost during optimization.

Location: Query, Data Type: boolean

mode_crop(optional)

Specifies the cropping mode for the image.

Location: Query, Data Type: string

option(optional)

Defines an option for image processing.

Location: Query, Data Type: string

quality(optional)

Specifies the desired quality of the image.

Location: Query, Data Type: integer

scale(optional)

Specifies the scale factor for resizing the image.

Location: Query, Data Type: integer

width(optional)

Specifies the desired width of the image.

Location: Query, Data Type: integer

x(optional)

Defines the x-coordinate position of the image.

Location: Query, Data Type: integer

y(optional)

Defines the y-coordinate position of the image.

Location: Query, Data Type: integer

var myHeaders = new Headers();
      myHeaders.append("apikey", "{API-KEY}");
      
      var raw = "{body}";
      
      var requestOptions = {
        method: 'POST',
        redirect: 'follow',
        headers: myHeaders,
        body: raw
      };
      
      fetch("https://api.apilayer.com/image_upload/upload?delay={delay}", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));


    import requests
  
    url = "https://api.apilayer.com/image_upload/upload?delay={delay}"
    
    payload = "{body}".encode("utf-8")
    headers= {
      "apikey": "{API-KEY}"
    }
    
    response = requests.request("POST", url, headers=headers, data = payload)
    
    status_code = response.status_code
    result = response.text


    $curl = curl_init();
  
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.apilayer.com/image_upload/upload?delay={delay}",
      CURLOPT_HTTPHEADER => array(
        "Content-Type: text/plain",
        "apikey: {API-KEY}"
      ),
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_ENCODING => "",
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_TIMEOUT => 0,
      CURLOPT_FOLLOWLOCATION => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_POSTFIELDS =>"{body}"
    ));
    
    $response = curl_exec($curl);
    
    curl_close($curl);
    echo $response;


    package main
  
    import (
      "fmt"
      "net/http"
      "io/ioutil"
    )
    
    func main() {
      url := "https://api.apilayer.com/image_upload/upload?delay={delay}"
    
      payload := strings.NewReader("{body}")
    
      client := &http.Client {}
      req, err := http.NewRequest("POST", url, payload)
      req.Header.Set("apikey", "{API-KEY}")
    
      if err != nil {
        fmt.Println(err)
      }
      res, err := client.Do(req)
      if res.Body != nil {
        defer res.Body.Close()
      }
      body, err := ioutil.ReadAll(res.Body)
    
      fmt.Println(string(body))
    }


    import java.io.*;
    import okhttp3.*;
    
    public class main {
      public static void main(String []args) throws IOException{
        OkHttpClient client = new OkHttpClient().newBuilder().build();
    
        MediaType mediaType = MediaType.parse("text/plain");
        RequestBody body = RequestBody.create(mediaType, "{body}");
    
        Request request = new Request.Builder()
          .url("https://api.apilayer.com/image_upload/upload?delay={delay}")
          .addHeader("apikey", "{API-KEY}")
          .method("POST", body})
          .build();
        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
      }
    }


    require "uri"
    require "net/http"
    
    url = URI("https://api.apilayer.com/image_upload/upload?delay={delay}")
    
    https = Net::HTTP.new(url.host, url.port);
    https.use_ssl = true
    
    request = Net::HTTP::Post.new(url)
    request['apikey'] = "{API-KEY}"
    request.body = "{body}"
    response = https.request(request)
    puts response.read_body


    curl --request POST \
    --url 'https://api.apilayer.com/image_upload/upload?delay={delay}' \
    --header 'apikey: {API-KEY}' \
    --data-raw '{body}'


    var client = new RestClient("https://api.apilayer.com/image_upload/upload?delay={delay}");
    client.Timeout = -1;
    
    var request = new RestRequest(Method.POST);
    request.AddHeader("apikey", "{API-KEY}");
    
    request.AddParameter("text/plain", "{body}",  ParameterType.RequestBody);
    
    IRestResponse response = client.Execute(request);
    Console.WriteLine(response.Content);


    import Foundation
  
    var semaphore = DispatchSemaphore (value: 0)
    let parameters = "{body}"
    let postData = parameters.data(using: .utf8)
    request.httpMethod = "POST"
    request.httpBody = postData
    
    let url = "https://api.apilayer.com/image_upload/upload?delay={delay}"
    var request = URLRequest(url: URL(string: url)!,timeoutInterval: Double.infinity)
    request.httpMethod = "POST"
    request.addValue("{API-KEY}", forHTTPHeaderField: "apikey")
    
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
      guard let data = data else {
        print(String(describing: error))
        return
      }
      print(String(data: data, encoding: .utf8)!)
      semaphore.signal()
    }
    
    task.resume()
    semaphore.wait()


    CURL *curl;
    CURLcode res;
    curl = curl_easy_init();
    if(curl) {
      curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
      curl_easy_setopt(curl, CURLOPT_URL, "https://api.apilayer.com/image_upload/upload?delay={delay}");
      curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
      curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");
      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, "apikey: {API-KEY}");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    
    const char *data = "{body}";
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
    
      res = curl_easy_perform(curl);
    }
    curl_easy_cleanup(curl);

** A word enclosed with curly brackets “{ }” in the code means that it is a parameter and it should be replaced with your own values when
executing. (also overwriting the curly brackets).

Returns

Below is a sample response from the endpoint


    {
      "height": 1341,
      "image_url": "https://core-production-us-east-1-imageupload.s3.amazonaws.com/0000_372ad59df94349add/7cc4f687_google2.0.0.jpg",
      "name": "google2.0.0.jpg",
      "new_height": 1341,
      "new_width": 2012,
      "optimized_size": 109748,
      "saved_bytes": 130313,
      "size": 240061,
      "success": true,
      "width": 2012
    }

Rate Limiting

Each subscription has its own rate limit. When you become a member, you start by choosing a rate limit that suits your usage needs. Do not worry; You can upgrade or downgrade your plan at any time. For this reason, instead of starting with a larger plan that you do not need, we can offer you to upgrade your plan after you start with “free” or “gold plan” options and start using the API.

When you reach a rate limit (both daily and monthly), the service will stop responding and returning the HTTP 429 response status code (Too many requests) for each request with the following JSON string body text.


{
    "message":"You have exceeded your daily\/monthly API rate limit. Please review and upgrade your subscription plan at https:\/\/apilayer.com\/subscriptions to continue."
}

A reminder email will be sent to you when your API usage reaches both 80% and 90%, so that you can take immediate actions such as upgrading your plan in order to prevent your application using the API from being interrupted.

You can also programmatically check your rate limit yourself. As a result of each request made to the APILayer, the following 4 fields provide you with all the necessary information within the HTTP Headers.x-ratelimit-limit-month: Request limit per month

x-ratelimit-remaining-month: Request limit remaining this month

x-ratelimit-limit-day: Request limit per day

x-ratelimit-remaining-day: Request limit remaining today

You can contact our support unit if you need any assistance with your application regarding to handle the returned result by looking at the header information.

Error Codes

APILayer uses standard 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 a clientside error, which means that failed given the information provided (e.g., a missing parameter, unauthorized access etc.). Codes in the 5xx range indicate an error with APILayer’s servers (normally this should’nt happen at all).

If the response code is not 200, it means the operation failed somehow and you may need to take an action accordingly. You can check the response (which will be in JSON format) for a field called ‘message’ that briefly explains the error reported.

Status Code	Explanation
400 – Bad Request	The request was unacceptable, often due to missing a required parameter.
401 – Unauthorized	No valid API key provided.
404 – Not Found	The requested resource doesn’t exist.
429 – Too many requests	API request limit exceeded. See section Rate Limiting for more info.
5xx – Server Error	We have failed to process your request. (You can contact us anytime)

You can always contact for support and ask for more assistance. We’ll be glad to assist you with building your product.

Documentation

Contents:

Image Upload API Reference

Just Getting Started?

Authentication

Endpoints

POST /upload

Parameters

Returns

POST /url

Parameters

Returns

Rate Limiting

Error Codes

product

Docs & Help

Account

Support