API Documentation

giflayer API

The giflayer API was built to provide a powerful and simple way to perform Video to GIF Conversion at an unparalleled speed and a quality of up to 30 FPS (Frames per Second), supporting all major video portals (e.g. YouTube, Vimeo, Vine, ... ), direct video links and video file formats.

Integrating our GIF conversion engine into your application will enable you to automatically generate GIFs with a full-featured suite of customization options at your disposal. These include Cropping, Resizing, creating Trailers, setting Start, End and Duration parameters, specifying your preferred FPS, and more.

API Requests are made using an easy-to-use URL structure, GIFs are delivered within a matter of seconds, and all API messages and notifications are returned in handy and lightweight JSON format. The following API documentation intends to provide interactive usage guides, detailed descriptions, and code examples for different programming languages.


Specs & Overview

API Access Key & Authentication

After signing up, every user is assigned a personal API Access Key - a unique "password" used to make requests to the API.

To authenticate with the numverify API, simply attach your access_key to the base endpoint URL:

http://apilayer.net/api/capture?access_key=YOUR_ACCESS_KEY  
                

Get your free API Access Key


Make an API Request

Requesting the API to perform a Video to GIF conversion is simple. Simply authenticate using the API's access_key parameter, pass your preferred video URL into the url parameter, and specify start and end values (in seconds, decimals allowed).

Most basic API request:


Take a look at the following API request URL: (If you would like to try it yourself, get a Free Plan and don't forget to attach your Access Key to the URL)

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = https://www.youtube.com/watch?v=3W6hZR29l5o
    & start = 0
    & end = 4
                

After executing this API request, the giflayer API will return your GIF within seconds. However, there are many more optional parameters that can be used to customize the end product. Find some of them below:

Optional parameters:

duration         paired with either "start" or end" it provides       Default: none
                 an alternative way to define the GIF's duration
               
size             resize the GIF to the dimensions of your             Default: 300x200
                 choice (accepts width and height in pixels)
               
crop             crop the GIF to the size of your choice              Default: none
                 (accepts width and height in pixels)
                 
fps              specify a GIF quality (Frames per Second)            Default: 15
                 of your choice (accepts number)
                 
trailer          set to "1" to create default trailer,                Default: none
                 or specify custom trailer parameters 
                

There is a full-featured GIF testing tool right in your Account Dashboard »


URL Encoding


Strictly speaking, it is always a safer method to URL encode video URLs before passing them into the API's url parameter. However, URL encoding is required in case your video URL contains the special character &.

Example URLs:

Find below an example video url that is required to be URL encoded in order to be processed correctly.

http://website.com?parameter=example&file=video.mp4
                

Example query:

This is how the example URL above has to be passed into an API request:

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = http%3A%2F%2Fwebsite.com%3Fparameter%3Dexample%26file%3Dvideo.mp4
    [...]
                

Not sure about URL encoding? Have a look at this reference page »


256-bit HTTPS Encryption
Basic Pro Enterprise

Paid Customers may establish a secure connection (industry-standard SSL) to the giflayer API and all data provided by and accessible through it.

To connect securely, simply attach an s to the HTTP Protocol. (resulting in https://)


API Error Codes

If your query fails, the giflayer API will return a 3-digit error-code, an internal error type and a plain text "info" object containing suggestions for the user.

Find below an example error - triggered when no URL was specified:

{
  "success": false,
  "error": {
    "code": 210,
    "type": "invalid_url",
    "info": "You have supplied an invalid URL. [make sure to include the HTTP protocol - example: http://domain.com]"    
  }
}
                


Common API errors:


Type Message Description
404 "404_not_found" User requested a resource which does not exist.
101 "missing_access_key" User did not supply an Access Key.
101 "invalid_access_key" User entered an invalid Access Key.
103 "invalid_api_function" User requested a non-existent API endpoint or function.
210 "invalid_url" User did not provide a valid URL.

show all errors


API Features

GIF Start & End
Free Basic Pro Enterprise

The most basic way of generating a GIF using the giflayer API is passing a video URL into the API's url parameter and appending your preferred start and end parameters.

Example query:

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = https://www.youtube.com/watch?v=3W6hZR29l5o
    & start = 10
    & end = 15
                

Format:


Parameter Format Default
start Number between 0 and 6000, decimals (using dot) allowed. -
end Number between 1 and 6000, decimals (using dot) allowed. -


GIF Duration

Instead of providing both start and end parameters, the API offers the possibility to ommit either one and specify a duration parameter.

Depending on which of the start and end parameters you pair with this duration parameter, you will receive different results.


Example using "start" & "duration":

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = https://www.youtube.com/watch?v=3W6hZR29l5o
    & start = 10
    & duration = 5
                

By providing the duration parameter in combination with start the giflayer API will be requested to generate a GIF starting at second 10 (start) and ending at second 15 (start + duration) of specified video.


Example using "end" & "duration":

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = https://www.youtube.com/watch?v=3W6hZR29l5o
    & end = 10
    & duration = 5
                

By providing the duration parameter in combination with end the giflayer API will be requested to generate a GIF starting at second 5 (end - duration) and ending at second 10 (end) of specified video.


Format:


Parameter Format Default
duration Number between 1 and 30. Must not be higher than a specified end parameter. Decimals (using dot) allowed. -


Resize GIF

Using the giflayer API's size parameter you may resize the requested GIF to the dimensions of your choice (format: width x height in pixels).

Example query:

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = https://www.youtube.com/watch?v=3W6hZR29l5o
    & start = 10
    & end = 15
    & size = 200x150
                

Format:


Parameter Format Default
size width x height, in pixels 300x200

Please note: The API's size parameter supports a minmum value of 50x50 and a maximum value of 5000x5000.


Crop GIF

Using the giflayer API's crop parameter you may crop the requested GIF to the size of your choice (format: width x height in pixels).

Example query:

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = https://www.youtube.com/watch?v=3W6hZR29l5o
    & start = 10
    & end = 15
    & crop = 100x100
                

Format:


Parameter Format Default
crop width x height, in pixels -

Please note: The API's crop parameter supports a minmum value of 50x50 and a maximum value of 5000x5000.


FPS (Frames per Second)

You may specify your preferred GIF resolution (in FPS) by appending a value between 1 and 30 to the API's fps parameter.

Example query:

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = https://www.youtube.com/watch?v=3W6hZR29l5o
    & start = 10
    & end = 15
    & fps = 10
                

Format:


Parameter Format Default
fps numerical value between 1 and 30, in Frames per Second 10



FPS Example GIFs


The following three GIFs very well illustrate the differences in resolution based on your choice of FPS (Frames per Second). Click on each gray button to show the example GIF at the respective FPS rate.




Important: Please be aware that a GIF's FPS resolution has a significant impact on its file size. The above example GIF's file size amounts to 2.8MB (MegaByte) at 10 FPS, while the 30 FPS version almost reaches 7MB.


Trailer

Additionally to the conventional way (described up to this point) of generating GIFs, the giflayer API offers the capability of creating a default or customizable GIF trailer (preview) of the requested video file.

By appending the API's trailer parameter to the request URL and setting it to 1 you will request the API to make use of the default trailer functionality, which splits the requested video into 10 equal parts, and plays 10% of each part before jumping to the next one, until the 10th part has been reached.

Example query:

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = https://www.youtube.com/watch?v=3W6hZR29l5o
    & trailer = 1
                


Trailer - Advanced Functionality


In case the default usage of the API's trailer parameter does not fit your needs, the giflayer API also offers the capability to generate a customized trailer of the requested video.

As implied earlier, the trailer feature is based on two values: The amount of parts the requested video is split into, and the length of each part.

These two values are both specified by appending the trailer parameter to the API request URL and setting it to number of parts, part length (as % of part)

Example: User requests a 4-minute video and specifies trailer=4,5. The first number (4) indicates that the video is split into 4 equal parts, each 1 minute long. The second number (5) indicates that 5% (= 3 seconds) of each part are played, until all 4 parts have been played. The duration of this GIF trailer would therefore amount to 12 seconds (4 x 3 seconds).

Example query:

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = https://www.youtube.com/watch?v=3W6hZR29l5o
    & trailer = 4,5
                

Format:


Parameter Format Default
trailer set to 1 for default usage, or set to number of parts, part length as % of part (comma-separated) for custom usage. -


Please note: The API's trailer parameter is not configured to accept decimals.

Important: The amount of trailer parts must be a numeric value between 2 and 20, and the part-length percentage must be a numeric value between 1 and 50.



Trailer - GIF Duration - Start & End


If no start, end or duration parameters are provided along with the trailer function, the giflayer API will automatically evaluate the entire length of the requested video for the creation of your trailer.

However, in order to restrict the trailer function to a certain timeframe, or to ensure a reduced GIF file size, you may specify these parameters according to to their usage guide above.

Important: Please note that since the standard GIF duration limit of 30 seconds is not applicable when working with trailers, GIF file sizes may be significantly larger.


Export to AWS S3

You may request the API to directly export your GIF to your AWS S3 Bucket. This can be done simply by appending your S3 Bucket path (format: s3://API_KEY:API_SECRET@bucket) to the API's export parameter.

Example query:

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = https://www.youtube.com/watch?v=3W6hZR29l5o
    & export = s3://DHSJ2HDGALIIDHSJDGAH:7SH6s7Sw9DKSH7h8Zs9Bw9DKSSH7h86s7Sw9Bw9D@mybucket.test/path/to   
                

Important: Uploading your GIF to the given S3 path may take several minutes to complete. Please be aware that our system can only attempt accessing the specified export path and cannot notify you in case your upload fails.


Export to FTP

You may also specify a custom ftp path to directly export captured GIFs to. This can be achieved simply by appending your desired FTP path (format: ftp://user:password@server) to the API's export parameter.

Example query:

http://apilayer.net/api/capture
    ? access_key = YOUR_ACCESS_KEY
    & url = https://www.youtube.com/watch?v=3W6hZR29l5o
    & export = ftp://myusername:mypassword@123.12.12.1/path/to   
                

Important: Uploading your GIF to the given FTP path may take several minutes to complete. Please be aware that our system can only attempt accessing the specified export path and cannot notify you in case your upload fails.


Language Examples

PHP

Capture GIFs in PHP:

Find below a simple PHP function that lets you generate a GIF and define all required and optional parameters:

function giflayer($url, $args) {

  // set access key
  $access_key = "YOUR_ACCESS_KEY";
  
  // encode target URL
  $params['url'] = urlencode($url);

  $params += $args;

  // create the query string based on the options
  foreach($params as $key => $value) { $parts[] = "$key=$value"; }

  // compile query string
  $query = implode("&", $parts);

  return "http://apilayer.net/api/capture?access_key=$access_key&$query";

}

// set required parameters
$params['start']  = '';    
$params['end'] = '';      

// set optional parameters (leave blank if unused)
$params['duration']  = '';    
$params['size'] = '';      
$params['crop']  = '';  
$params['fps'] = '';      
$params['trailer'] = '';      
$params['export'] = '';      

// capture
$call = giflayer("https://www.youtube.com/watch?v=3W6hZR29l5o", $params);                
                

Please note: Optional parameters may be left blank if they are not being used.


Ruby

Capture GIF via Ruby:

Find below a Ruby function that lets you capture a GIF and define all required and optional parameters:

                
require 'cgi' unless defined?(CGI)
 
def giflayer(url, options={})
    
  # set access key
  access_key = 'YOUR_ACCESS_KEY'
  
  # define parameters
  parameters = {
    :url       => url,
    :start  => options[:start],
    :end  => options[:end],
    :duration  => options[:duration],
    :size  => options[:size],
    :crop  => options[:crop],
    :fps  => options[:fps],
    :trailer  => options[:trailer],
    :export  => options[:export],
  }
   
  query = parameters.
    sort_by {|s| s[0].to_s }. 
    select {|s| s[1] }.       
    map {|s| s.map {|v| CGI::escape(v.to_s) }.join('=') }.
    join('&')
  
  "http://apilayer.net/api/capture?access_key=#{access_key}&#{query}"
end
 
# set url (required), optional parameters (leave blank if unused) & call function
puts giflayer("https://www.youtube.com/watch?v=3W6hZR29l5o",{ 
    start: "", 
    end: "", 
    duration: "", 
    size: "", 
    crop: "", 
    fps: "", 
    trailer: "", 
    export: "" })                   
                
                

Please note: Optional parameters may be left blank if they are not being used.


Python

Capture GIF using Python:

Building a query to capture a GIF using Python is as simple as:

                
#!/usr/bin/python
 
import hmac
import hashlib
import urllib
 
 
def giflayer(access_key, url, args):
    
    # encode URL
    query = urllib.urlencode(dict(url=url, **args))
 
    return "http://apilayer.net/api/capture?access_key=%s&%s" % (access_key, query)

# set optional parameters (leave blank if unused)
params = {
    'start': '',
    'end': '',
    'duration': '',
    'size': '',
    'crop': '',
    'fps': '',
    'trailer': '',
    'export': ''
};
 
# set your access key and video URL 
access_key = "YOUR_ACCESS_KEY"
url = "https://www.youtube.com/watch?v=3W6hZR29l5o"
 
print giflayer (access_key, url, params)

                

Please note: Optional parameters may be left blank if they are not being used.


Help / Support


Any issues with API Integration? Be sure to take a look at our Frequently Asked Questions to see if your question has already been answered.

Still need something clarified? Please get in touch with our support team at support@apilayer.net.