HTML5 Animation to GIF - API

  • Introduction

  • This document covers API details for making an animated GIF from your HTML5 or CSS-based animation. Following are the basic steps:
    1. 1. Upload your HTML5 creative as a zip file (i.e. your html file should include links to javascript, CSS, and images) or as an url (hosted on your server). 
    2. 2. GIF rendering call with parameters like height, width, duration, etc.
    3. 3. Webhook information to get a downloadable URL once an animated GIF gets created.
    4. 4. A pinging service to wait for GIF output and its ongoing progress.
  • Method: Uploadzip

  • Description:

    This service is used to upload a zip file of your HTML5 creative. A zip file should contain one html file along with its dependent resources like CSS, Javascript, and images. This service returns "creativeid" in the response, which is used in subsequent service calls. Please Note: If you want to generate a GIF from an http url hosted on your server (instead of a zip file), then please do not use this service and move to the next service, ‘UploadUrl’.

  •                                     Service url: https://html5animationtogif.com/api/uploadzip.ashx 
                                    
  • Request Body Parameters

  • Parameter Description Data Type
    FileData Post your zip file as multipart form data.. Muitipart form data
  • Response Body Parameters

  • Parameter Description Data Type
    status Status of the execution. Possible values are "success" and "error. string
    creativeid Unique ID of the uploaded zip. This is a reference ID. It has to be used in the subsequent service "converttogif.ashx". string
    message Error message (if any) string
  • Success response example

  •                                      { "status": "success",  "creativeid": "creative_550x550_10ed7e8783" }
                                    
  • Error response example

  •                                      { "status": " error ",  "message” ": "No file has been uploaded. " }
                                    
  • Method: UploadUrl

  • Description:

    This service is used to post the "http url" of your HTML5 creative. This "http url" should be hosted on your server. It returns "creativeid" in response, which is used in subsequent service calls.

    Please Note: If you are uploading a zip file of your HTML5 creative, then please do not use this service and refer to the "UploadZip" service.

  •                                     Service url: https://html5animationtogif.com/api/uploadurl.ashx 
                                    
  • Request Body Parameters

  • Parameter Description Data Type
    url Http url of your HTML5 creative string
  • Response Body Parameters

  • Parameter Description Data Type
    status Status of execution. Possible values are “success” and “error”. string
    creativeid HTML5 creative identifier. This is a reference ID. It has to be passed in the next service, "converttogif.ashx". string
    message Error message (if any) string
  • Success response example

  •                                     { "status": "success",  "creativeid": "creative_550x550_10ed7e8783" }
                                    
  • Error response example

  •                                     { "status": " error ",  "message” ": "No file has been uploaded. " }
                                    
  • Method: ConvertToGif

  • Description:

    This service converts your HTML5 creative into an animated GIF. This service initiates the rendering call asynchronously. It returns'mediaid' as a response, and'mediaid' is used to check the progress of rendering/encoding via service call 'CheckStatus'. 

    If you are providing information about the webhook url, then you don't need to check the status of execution; our service will automatically post the "downloadable url" of the output to the webhook url.

  •                                     Service url: https://html5animationtogif.com/api/converttogif.ashx  
                                    
  • Request Body Parameters

  • Parameter Description Data Type
    clientid ID of the customer. It is provided at the time of registration or through email. string
    apikey A special code to access the API. It is given either at registration or by email. string
    creativeid ID of the uploaded creative. It is returned in response to "uploadzip" or "uploadurl" service call. string
    height Height of the creative. Our service supports both 1920x1080 and 1080x1920 resolutions. number
    width Width of the creative. Our service supports both 1920x1080 and 1080x1920 resolutions. number
    duration Duration of the creative. (or duration of a loop) number
    starttime Ignore the first few seconds of the animation, then record a gif. Defualt value is 0. number
    loop GIF looping. For the "forever" loop, pass the value loop=0. Possible values range from 0 to 1000. Please Note: If your animation has more than one loop, then you should provide the "duration" of one loop, not the total duration including all loop counts. number
    fps Frames per second. The minimum value is 2 and the maximum is 30. number
    webhookurl Default value is “” (i.e webhookurl=""). A webhook is a notification sent to your application once a gif gets created. Your application must provide an http url in order to receive parameters from our service. Once the gif is created, 
    The following parameters are posted to the webhook url:
    1. downloadurl
    2. mediaid
    3. creativeid
    For example, webhookurl=https://yourserver/getvideostatus/..
    You can access the parameter in your page as follows:
    var url = Request[“downloadurl”];
    downloadurl: a download URL for the gif. Your app should download it and host it on your server.
    mediaid: gif identification in our system.
    creativeId: Your html creative's unique id on our server.
    string
    creativefitoption This option specifies, how creative elements are positioned in the browser. Possible values are "lefttop" and "center." The default value is "lefttop". string
    encoder This option specifies to encode gif with a given encoder.
    Possible values are: FFMPEG,LWZENCODER,IMAGEMAGIC,GIFISKI
    The default value is FFMPEG.
    Following are descriptions:
    IMAGEMAGIC:This is slightly slow encoder, it creates gif with good colors and optimized file size. Best for photo, Anything taken by a camera, digital camera, or photocopier.
    FFMPEG:This is a fast encoder; it creates gifs with good to moderate quality (256 colors only) and an optimized file size. Best for picture, A drawing, painting, or artwork created on a computer.
    GIFISKI:This is a fast encoder; it creates high-quality gifs with original or true color (i.e., 32 bits) and a slightly larger file size.
    LWZENCODER:This is fast encoder, it creates gif with good/moderate (256 colors only) and optimized file size.
    string
    quality This option specifies the quality of the GIF.
    Possible values are: 0,1,2,3 or 4 Default value is 3 (i.e 75% quality)
    Pass one of the above values on the request, and these values are equivalent to 15%,25%,50%,75%or 100%
    string
    maxsize Specifies the gif's target file size in KB. For example, 150, 80, etc. (i.e maxsize=150) This is an optional parameter, and the default value is 0. The maximum supported value is 10000 KB, and the minimum supported value is 20 KB.  Please Notes: To achieve the target file size, render makes multiple attempts. The renderer can reduce the given FPS and quality (if needed). For example: if you want to achieve a target file size of 150 kB at 5 fps, Render will first create a gif as is, then check the file size. If the file size is still greater than 150 kB, rendering will reduce the frame rate and quality to meet the target file size. There could be multiple iterations in this process. number
  • Response Body Parameters

  • Parameter Description Data Type
    status Status of the execution. Possible values are “success” and “error”. string
    mediaid ID for the media. Use this value in the "checkstatus" service to know the status of processing. string
    message Error message (if any) string
  • Success response example

  •                                     { "status": "success",  "message": "",  " mediaid ": "34488" }
                                    
  • Error response example

  •                                     { "status": "error",  "message": "Invalid API key or Client Id" }
                                    
  • Method: Checkstatus

  • Description:

    This service is used to check the status of conversions. It should be invoked after the "converttogif" service. This service can be invoked periodically (or at intervals).
    Please Note: If you are passing 'webhook' url (in the converttogif service), then skip this service. Once the gif is created, the url and other information will be automatically posted to the webhook url. 

  •                                     Service url:  https://html5animationtogif.com/api/checkstatus.ashx 
                                    
  • Request Body Parameters

  • Parameter Description Data Type
    creativeid ID of the creative. String
    mediaid ID of the media. String
    fileext gif String
  • For example

  •                                     https://html5animationtogif.com/api/checkstatus.ashx?
    creativeid=creative_550x550_10ed7e8783&mediaid=34488&fileext=gif
  • Response Body Parameters

  • Parameter Description Data Type
    status Status of the service call. Possible values are “success” and “error”. string
    jobstatus Status of the processing. string
    message Error message (if any) string
    url Download Url of GIF. string
  • Success response example

  •                                      
    Specifies, scrapping of content 
    { “status”: "success",  "jobstatus": "Scraping content. Please wait...",  "url": "" }
    
    Specifies, encoding of gif
    
    { "status": "success",  "jobstatus": "20%",  "url": "" }
    { "status": "success",  "jobstatus": "40%",  "url": "" }
    { "status": "success",  "jobstatus": "90%",  "url": "" }
    
    Specifies, gif has been created.
    { "status": "success",  "jobstatus": "done",  "url": "https://html5animationtogif.com/API/mediadownload.ashx?mediaid=34488&creativeid=creative_550x550_10ed7e8783&fileext=gif&inline=y" }
                                    
  • Error response example

  •                                     { "status": "error",  "message": "File doesn't exist." }
                                    
  • Synchronization of gif with its actual Start and End time

  • Problem Definition:

    You have been experiencing that sometimes HTML5 creative takes time to load in the browser before actual animation gets started. Also, sometimes HTML5 animation displays a loader until content gets loaded in the browser. It is a challenge to ask the gif renderer to wait and then start recording the gif. It is challenging to record gifs from the actual start to the end.

     

    Solution:

    To solve such a problem, you need to place the following javascript code inside the javascript file of your HTML5 creative. In your javascript, call the 'trim_start' function when the animation begins and the 'trim_end' function when it is finished/ended.

                                        
    var trim_request_url = "http://localhost/capturestart/trim_media.ashx";
    
    function trim_start() 
    {
        try {
            var timeinmilisec = Math.abs(new Date() - new Date("1970/01/01"));
            var request = new XMLHttpRequest();
            request.open('GET', trim_request_url + "?action=start&time=" + timeinmilisec, true); 
            request.send(null);
        } catch{ }
    
    }
    
    
    function trim_end() {
        try {
            var timeinmilisec = Math.abs(new Date() - new Date("1970/01/01"));
            var request = new XMLHttpRequest();
            request.open('GET', trim_request_url + "?action=end&time=" + timeinmilisec, true);  
            request.send(null);
        } catch{ }
    
    }
    
                                            
                                          

    Please note: the duration of the animation should be calculated by adding an approximate content's load-time in the browser and calculated value should be passed with the "duration" attribute of "converttogif" service. See the picture below.

    The renderer will open the animation in the browser, it takes some time to load the content. Animation's javascript should invoke trim_media.ashx with the "start" action. Once the animation reaches its end, Animation's javascript should invoke trim_media.ashx with the "end" action. In the above example shown in the picture, the animation starts at 3 seconds and ends at 9 seconds. Hence the "duration" should be passed as 9+ 2 = 11 seconds with the "converttogif" service. Here, 2 seconds are just for the buffer. Gif or video will be created length of 6 seconds in above example.

  • Download: Sample

  • Javascript sample code for API integration:

    We have created sample code in javascript and placed it inside the html file. Your developer can refer to it for API integration. Please see the following link to download sample code. 

    Download

  •                                     
        
        
        //-- Init --//
        var clientid = "1062";
        var apikey = "17gfdc80-b1be-459b-52b7-f12cbf6ef077";
        var creativeid = "";
        var mediaid = "";
        function SendVideoRequest(myobj) {
            //-- Upload URL --//
            myobj.style.display = "none";
    
            var data = new FormData();
            data.append("url", "https://previews.envatousercontent.com/files/240056227/banners/A/728x90/index.html");
            
            
    
            var xhr = new XMLHttpRequest();
            xhr.open('POST', 'https://html5animationtogif.com/api/uploadurl.ashx', true);
            xhr.onload = function () {
                var response = JSON.parse(xhr.responseText);
                if (response.status == "success") {
                    creativeid = response.creativeid;
                    
                    console.log("creativeid=" + creativeid);
                    
                    convert_gif(creativeid);
                } else {
                    alert(response.message)
                }
            };
            xhr.send(data);
    
        }
    
      
    
        //-- Convert GIF --//
        function convert_gif(id) {
            var data = new FormData();
            
            
            data.append("width", "728");
            data.append("height", "90");
            data.append("duration", "9");
    
            data.append("fps", "12");
            data.append("audio", "N");
            data.append("webhookurl", "");
            // A webhook url is a simple http web address (hosted on your server) that should accept the parameter "download url" from html5animationtogif.com once the output is ready. Refer to the document for more details.
    
            data.append("creativefitoption", "lefttop");
            data.append("clientid", clientid);
            data.append("apikey", apikey);
            data.append("creativeid", id);
            data.append("maxsize", "");
            data.append("quality", "3"); // Possible values 1 (low quality) or 2 or 3 or 4 (best quality)
            data.append("loop", "1"); // 0 for forever
            
           
            var xhr = new XMLHttpRequest();
            xhr.open('POST', 'https://html5animationtogif.com/api/converttogif.ashx', true);
            xhr.onload = function () {
                var response = JSON.parse(xhr.responseText);
                if (response.status == "success") {
                    mediaid = response.mediaid;
                    
                    document.getElementById("txtResponse").style.display = "block";
                    WaitForOutput();
                } else {
                    alert(response.message)
                }
            };
            xhr.send(data);
        }
    
        function WaitForOutput() {
    
            var xhr = new XMLHttpRequest();
            xhr.open('GET', "https://html5animationtogif.com/api/checkstatus.ashx?creativeid=" + creativeid + "&mediaid=" + mediaid + "&fileext=gif", true);
          
            xhr.onload = function () {
                
                document.getElementById("txtResponse").value = xhr.responseText;
                var response = JSON.parse(xhr.responseText);
                
                if (response.status == "success") {
                    if (response.jobstatus != "done") {
    
                        window.setTimeout(WaitForOutput, 2000);
                    }
                    else if (response.jobstatus == "done") {
    
                        window.open(response.url);
    
                    }
                }
                else if (response.status == "error") { alert(response.message) }
            };
            xhr.send();
    
        }