FileZigZag Conversion API Documentation

Welcome Getting started Tutorial Credit cost Reference get_all_sourcefmts get_targetfmts conv_permitted conv_init conv_setsource conv_query Notes

Welcome

Welcome to FileZigZag conversion API. It is built with REST architecture and is compatible with a wide range of development languages (basically, any language that can send HTTP requests using GET, POST, etc methods). It supports the full set of (source-target) formats that FileZigZag.com supports.


Getting started

The first thing you need to do in order to start using the API is to get your own API secret key. A secret key is a special string of characters that is needed to be sent with every API call. Keep in mind that your secret key is personal, and it should not be shared. It is your responsibility to keep it away from other users or hackers/crackers.
You need to get a secret key only once. After that you can use it every time with all your requests.

Click here to register for a secret key

In short, to convert a file you call a specific API "function" sending the needed parameters (according to each function requirements) accompanied by your secret key, and spend credits to convert files according to their sizes. You must have enough credits in your account to convert files.

Click here to buy credits

All API requests are directed towards a unified endpoint: https://api.filezigzag.com/requests.php. This includes "real" as well as "sandbox" requests.

You are recommended to start testing the code examples using the "sandbox" mode, which is a special free mode that lets you test your code, send requests and inspect the responses without spending any credit. After you get familiar with the API and are ready to deploy your app to your users, you can switch to the "real" mode.

Note: the "sandbox" mode is designed for test purposes only, so it does NOT produce real converted files. It just returns the same uploaded file back to you. However it is useful to test your code because it otherwise behaves in the same way as the real mode.


Tutorial

This is a step-by-step tutorial on how to call the API. It descibes the steps you should implement in your application in order to make use of the API to convert a file. More detailed info about each call can be found in the Reference section.

  1. First, you should query the list of supported source formats. You cannot convert a file with a format not supported.

    You do so by sending an HTTP request using GET or POST methods, along with two parameters: func=get_all_sourcefmts, and secretkey=(Your secret key).

    In return, you get a JSON-encoded response, which has two members: retcode, and retdata.
    retcode (Numeric) Indicates whether the request succeeded or not.
    0 indicates success (no error), 1 indicates failure.
    retdata Its content depends on the value of retcode:
    • If retcode equals 0 (no error), this member will contain the required data (which is a list (array) of supported source formats).
    • If retcode equals 1, this member will contain a text string with description of the problem occurred.

    The following code snippet is an example of how to use this request and its response:
    JQuery
    C#
    cURL
    
    const FZZAPI_REQUESTS = 'https://api.filezigzag.com/requests.php';
    const SECRETKEY = 'XXX-XXXXXXX'; // Put your secret key here
    
    
    // Get all supported source formats
    function get_all_sourcefmts() {
       $.get(FZZAPI_REQUESTS, {func: "get_all_sourcefmts", secretkey: SECRETKEY}, function(response) {
          if (response.retcode == 0) {
             // Show the supported formats on the page
             $("#src_fmts").html(response.retdata.join(", "));
          } else {
             // Error occurred
             $("#src_fmts").html("Could not retrieve the list of formats! - Error: " + response.retdata);
          }
       });
    }
    						
    
    using System;
    using System.Net.Http;
    using System.Threading.Tasks;
    
    namespace MyApp
    {
       class Program
       {
          private const string FZZAPI_ENDPOINT = "https://api.filezigzag.com/requests.php";
          private const string MY_SECRETKEY = "XXX-XXXXXXX"; // Put your secret key here
    
          private static readonly HttpClient MyClient = new HttpClient();
    
          static async Task Main(string[] args)
          {
             var req_uri = FZZAPI_ENDPOINT + "?func=get_all_sourcefmts&secretkey=" + MY_SECRETKEY;
             var response = await MyClient.GetStringAsync(req_uri);
    
             Console.WriteLine(response);
          }
       }
    }
    						
    
    curl "https://api.filezigzag.com/requests.php?func=get_all_sourcefmts&secretkey=XXX-XXXXXXX"
    						
    Note: Don't forget to put your secret key instead of XXX-XXXXXXX.

    And here is an example of the response (JSON-encoded string):

    
    {
       "retcode": 0,
       "retdata": [
          "264","3g2","3ga","3gp","3gpp","7z","7zip","aac","ac3","ai","aif","aiff","amr","ar","arj", ...
       ]
    }
    				

    Note: The list is truncated (...) because it's too long. You usually get the full list in the response.

    Now that you have a list of supported "source formats", you can allow your users to select a file to be converted (maybe from their local device), with one of the supported source formats.


  2. After the user selects a file compatible with one of the "source formats" that were gotten in step 1, you should query the supported "target formats" which are the accepteble formats in which the file will be converted into.

    To do so, send another request, with parameters: func=get_targetfmts, sourcefmt=(The source format), and secretkey=(Your secret key).

    In return, you get a JSON-encoded response, with also two members: retcode, and retdata. Their interpretation is the same as in the 1st step, except that if retcode contains 0 (success), retdata will contain a list (array) of supported "target formats".


  3. Now we have the source and target formats. There is a recommended step before starting the conversion process. It's mandatory when you need to convert multiple files. This step is to send a request with func=conv_permitted, and only secretkey=(Your secret key) as a parameter.

    The response JSON will contain, as usual, two members: retcode and retdata. When retcode contains 0, this means it's permitted to start conversion and you can proceed to the next step.

    In general, it's recommended to always check the response of this request before you proceed to the next step.


  4. To start a conversion, you send a request with func=conv_init, and secretkey=(Your secret key). Now, in this request you can select whether you want a "real" or "sandbox" conversion. To select the "sandbox" mode, send sandbox=1 as a parameter along with the secretkey. If you omit the sandbox parameter, it's assumed that you want the "real" mode.

    The response is a JSON-encoded string with retcode and retdata as usual. If the request succeeded (retcode equals 0), retdata will contain another JSON object with two members: conv_id and conv_mode. Here is an example of a successful response:

    
    {
       "retcode": 0,
       "retdata": {
          "conv_id": "3ca785b7",
          "conv_mode": "real"
       }
    }
    				

    "conv_id" (Conversion ID) is a special ID specific to the current conversion. When you send a file to be converted (the next step), this ID must also be sent along. You can request to convert many files with the same conv_id, but then you should pay attention to the response of the conv_permitted request (see the previous step).

    Note: "conv_id" should be used immediately in a conv_setsource request (next step) after you get it. It has a lifetime and will expire if you don't use it for a while.

    "conv_mode" informs you of the selected conversion mode (sandbox or real). You should stick with the same mode during the conversion process (all the next requests), until you send a new conv_init with the needed mode.


  5. Now that you have the source and target formats and the conv_id, you start converting the file by uploading it, along with the parameters: func=conv_setsource, secretkey=(Your secret key), conv_id=(Conversion ID from step 4), targetfmt=(Target format from step 2), file=(User file to be converted), and if you want the sandbox mode, sandbox=1.

    This request only accept POST method. User file and other parameters should be sent using multipart/form-data.

    The following code snippet is an example of how to use both conv_init and conv_setsource requests:
    JQuery
    C#
    cURL
    
    const FZZAPI_REQUESTS = 'https://api.filezigzag.com/requests.php';
    const SECRETKEY = 'XXX-XXXXXXX'; // Put your secret key here
    const SANDBOX = false;
    
    
    function start_converting() {
       var status = $("#status"), reqdata;
    
       // 1) conv_init
       reqdata = {func: "conv_init", secretkey: SECRETKEY};
       if (SANDBOX) reqdata.sandbox = 1;
       $.get(FZZAPI_REQUESTS, reqdata, function(response1) {
          if (response1.retcode == 0) {
             status.html("Uploading file...");
    
             // 2) conv_setsource
             reqdata = new FormData();
             reqdata.append("func", "conv_setsource");
             reqdata.append("secretkey", SECRETKEY);
             reqdata.append("conv_id", response1.retdata.conv_id); // From "conv_init" request
             reqdata.append("file", $("#file_input")[0].files[0]); // From <input type="file"/>
             reqdata.append("targetfmt", $("#combo_targetfmts").val()); // From target formats <select>
             if (SANDBOX) reqdata.append("sandbox", 1);
    
             $.ajax({ // Using a long form of JQuery's Ajax
                type: "POST",
                url: FZZAPI_REQUESTS,
                processData: false,
                contentType: false,
                data: reqdata,
                dataType: "json",
                success: function(response2) {
                   // If response2.retcode == 0, this means the request was successful
                   console.log("conv_setsource:\r\n" + JSON.stringify(response2));
                }
             });
          } else {
             // Some error occurred
             console.log("conv_init:\r\n" + JSON.stringify(response1));
          }
       });
    }
    						
    
    using System;
    using System.IO;
    using System.Threading.Tasks;
    using System.Net.Http;
    using Newtonsoft.Json.Linq; // Needs adding NuGet Package: Newtonsoft.Json
    
    namespace MyApp
    {
       class Program
       {
          private const string FZZAPI_ENDPOINT = "https://api.filezigzag.com/requests.php";
          private const string MY_SECRETKEY = "XXX-XXXXXXX"; // Put your secret key here
    
          private static readonly HttpClient MyClient = new HttpClient();
    
          static async Task Main(string[] args)
          {
             var req_uri = FZZAPI_ENDPOINT + "?func=conv_init&secretkey=" + MY_SECRETKEY;
             var response1 = await MyClient.GetStringAsync(req_uri);
             JObject json_resp1 = JObject.Parse(response1);
    
             if (json_resp1.Value("retcode") == 0)
             {
                JObject r1_retdata = json_resp1.Value("retdata");
    
                // Target format (pdf), and user file are hard-coded here, only for simplicity
                string retstr = await SetSource(r1_retdata, "pdf", "D:\\Document.docx");
                Console.WriteLine(retstr);
             }
             else
             {
                Console.WriteLine("conv_init:\r\n" + response1); // Some error occurred
             }
          }
    
    
          static async Task SetSource(JObject R1_RetData, string TargetFmt, string UserFilePath)
          {
             var formData = new MultipartFormDataContent();
             
             HttpContent strFunc = new StringContent("conv_setsource");
             HttpContent strSecretKey = new StringContent(MY_SECRETKEY);
             HttpContent strConvID = new StringContent(R1_RetData.Value("conv_id"));
             HttpContent strTargetFmt = new StringContent(TargetFmt);
             HttpContent UserFile = new ByteArrayContent(File.ReadAllBytes(UserFilePath));
    
             formData.Add(strFunc, "func");
             formData.Add(strSecretKey, "secretkey");
             formData.Add(strConvID, "conv_id");
             formData.Add(strTargetFmt, "targetfmt");
             formData.Add(UserFile, "file", Path.GetFileName(UserFilePath));
    
             var response2 = await MyClient.PostAsync(FZZAPI_ENDPOINT, formData);
    
             return "conv_setsource:\r\n" + response2.Content.ReadAsStringAsync().Result;
          }
       }
    }
    						
    
    curl "https://api.filezigzag.com/requests.php?func=conv_init&secretkey=XXX-XXXXXXX"
    						
    Sample response:
    {"retcode":0,"retdata":{"conv_id":"0123abcd","conv_mode":"real"}}
    Now, use the "conv_id" in the next request (user file and target format are just examples):
    
    curl --form func=conv_setsource
         --form secretkey=XXX-XXXXXXX
         --form conv_id=0123abcd
         --form targetfmt=pdf
         --form file=@D:\Document.docx
         "https://api.filezigzag.com/requests.php"
    						
    Note: Don't forget to put your secret key instead of XXX-XXXXXXX.


    And if it's successful, this is a sample JSON response to the conv_setsource request:

    
    {
       "retcode": 0,
       "retdata": {
          "queue_id": "4321dcba",
          "conv_id": "1234abcd",
          "conv_mode": "real",
          "credit_cost": 1
       }
    }
    				

    "queue_id" (Queue ID) is a special ID specific for that file you uploaded. It's used in the next step conv_queryto check the conversion status of the file.

    "conv_id", and "conv_mode" are the same values that you have passed as parameters to this request. Returned in the response just for your reference.

    "credit_cost" determines how much credits was deducted from your account. Applies only when you select the "real" mode (or not sending sandbox=1 parameter in the rquest).

  6. The final step is to check the status of the file you have uploaded in the previous step. Possible statuses (for a successful request) are: "Queued" (with number of users ahead), "Converting", and "Done" (with a link to download the converted file).

    You send a request with func=conv_query, secretkey=(Your secret key), conv_id=(Conversion ID from step 4), queue_id=(Queue ID from step 5), and if you want sandbox mode, sandbox=1.

    This request can be sent repeatedly with a (3 to 10) seconds intervals, with the same parameters, until the file is done converting and you get the link to the converted file.

    The response consists of retcode and retdata as usual.

    And here is a sample JSON rsponse of a successful conversion process:

    
    {
       "retcode": 0,
       "retdata": {
          "status": 2,
          "ahead": 0,
          "conv_results": {
             "success": 1,
             "download_link": "https://www.filezigzag.com/api/getfile.php?cid=1234abcd&ofn=5fa2cc9c.pdf"
          }
       }
    }
    				

    retdata is a JSON object. The following is a describtion of some of its members:
    status (Numeric) Indicates the status of the conversion process.
    It have one of three values: 0 means "queued", 1 means "converting", and 2 means "done".
    ahead (Numeric) Indicates how many users are ahead of you in the conversion queue.
    It's used when the status member has the value of 0 (queued). Otherwise it's not used and usually contains 0.
    conv_results It exists only when the status member has the value of 2 (done).
    It's also a JSON object with these members:
    • success: Indicates whether the conversion was successful or not. Contains one of two values: 1 (succeeded), and 0 (failed).
    • error_str: valid when the success member has the value of 0 (failed). It's a text string with description of the error that has occurred.
    • download_link: valid when the success member has the value of 1 (succeeded). It's a URI to download the converted file (contains an endpoint plus parameters needed to download the file).
    Note: There are some other members of conv_results for this request not mentioned here to keep thing simple. Please, refer to the Reference section for more info about the request and its response.

    As a rule, you should always check retcode first, and if found successful you then check the status member of retdata, and only if it has the value of 2 (Done) you can finally read the download_link to download the converted file.

Finally, You can download the following sample applications which make use of most of the requests and can help you understand more about how these requests work.

Made with: HTML, Javascript (JQuery)
Made with: C#, Microsoft Visual Studio 2019

Notes:

Also, don't forget to read the Reference section, as it contains detailed info about each request and their expected responses.


Credit Cost

Credit cost depends on the uploaded file size. They are deducted from your account only when you use the "real" mode to convert. You usually fill your account with credits, and spend them on file conversion. In response to the conv_setsource request you receive a credit_cost member in the retdata member of the response, which indicates how much credits was consumed.

Click here to buy credits

The following table shows the amounts of credits needed for every range of file sizes:

File SizeCredit Cost
From 1 Byte to less than 1 MB 1 Credit
From 1 MB to less than 5 MB 2 Credits
From 5 MB to less than 25 MB 3 Credits
From 25 MB to less than 50 MB 5 Credits
From 50 MB to less than 100 MB 10 Credits
From 100 MB to less than 250 MB 25 Credits
From 250 MB to less than 500 MB 50 Credits
From 500 MB to 1 GB 100 Credits

Note: The minimum accepted file size is 1 Byte, and the maximum accepted file size is 1 GB.


Reference

This section describes each API request in details.

General rules:


get_all_sourcefmts
Description Gets a list of file types (formats) that are supported for source files (uploaded user files to be converted).
Method GET, POST
Parameters
  • func: get_all_sourcefmts
  • secretkey: (Your secret key)
Response
  • retcode: [Numeric] 0 (success) or 1 (failure)
  • retdata:
    • On success: [Array of strings] All supported source formats for user files.
    • On failure: [String] The error message.
Possible causes of failure
  • An invalid secret key.


get_targetfmts
Description Gets a list of target file types (formats) that a file can be converted into, for a specific source format.
Method GET, POST
Parameters
  • func: get_targetfmts
  • secretkey: (Your secret key)
  • One of:
    • sourcefmt: The format of the source file (e.g. "docx")
    • sourceurl: 1 (Send the value of 1 to indicate you want target formats for converting a URL.
Response
  • retcode: [Numeric] 0 (success) or 1 (failure)
  • retdata:
    • On success: [Array of strings] All supported target formats for that source format you specified in parameters.
    • On failure: [String] The error message.
Possible causes of failure
  • An invalid secret key.
  • An invalid source format.


conv_permitted
Description Determines if you can start a new conversion process or send the next file for conversion.
Method GET, POST
Parameters
  • func: conv_permitted
  • secretkey: (Your secret key)
Response
  • retcode: [Numeric] 0 (success: you can convert files) or 1 (failure: you cannot currently convert new files)
  • retdata: [String] Either you can convert files or an error message.
Possible causes of failure
  • An invalid secret key.
  • Another conversion (for the same secret key) is still going on.
  • A server maintainance is scheduled.


conv_init
Description Initializes a new conversion process, selects between "sandbox" or "real" modes, and returns a Conversion ID for later conversion-related operations.
Method GET, POST
Parameters
  • func: conv_init
  • secretkey: (Your secret key)
  • [Optional] sandbox: 1 (Send the value of 1 to indicate you want "sandbox" (testing) mode.
Response
  • retcode: [Numeric] 0 (success) or 1 (failure)
  • retdata:
    • On success: JSON object with two members:
      • conv_id: The Conversion ID for the current conversion. Use it for further conversion requests
      • conv_mode: The conversion mode ("sandbox" or "real"). It's the same mode you indicated in parameters. Returned here for your reference only.
    • On failure: [String] The error message.
Possible causes of failure
  • An invalid, or expired secret key.
  • New conversions not permitted yet. (see conv_permitted)
  • Selecting the "real" mode while having 0 credits.


conv_setsource
Description Sends a source file for conversion, along with other needed data like target format to convert into, and adds it to the conversion queue.
You should send this request immediately after you get the response of conv_init request.
Method POST (only)
Parameters Should be sent as multipart/form-data POST method data.
  • func: conv_setsource
  • secretkey: (Your secret key)
  • conv_id: (The Conversion ID, from conv_init)
  • One of:
    • file: (form-data binary file, with parameter name as "file").
    • url: [String] fully-qualified URL (e.g. "https://www.google.com").
  • targetfmt: The target format in which the file will be converted into (e.g. "pdf").
  • [Optional] sandbox: 1 (Send the value of 1 to indicate you want "sandbox" (testing) mode.
    This parameter should be the same as the one sent to the conv_init request.
Response
  • retcode: [Numeric] 0 (success) or 1 (failure)
  • retdata:
    • On success: JSON object with four members:
      • queue_id: The Queue ID for the current file. Use this for conv_query request.
      • conv_id: The Conversion ID for the current conversion. It's the same conv_id you sent as a parameter returned here only for your reference.
      • conv_mode: The conversion mode ("sandbox" or "real"). It's the same mode you indicated in parameters. Returned here only for your reference.
      • credit_cost: How much credits are needed for converting this file. Refer to Credit Cost for details.
    • On failure: [String] The error message.
Possible causes of failure
  • An invalid, or expired secret key.
  • New conversions not permitted yet. (see conv_permitted)
  • Invalid (or expired) Conversion ID.
  • Mismatched converison mode ("sandbox" or "real") between conv_init and conv_setsource.
  • Source file upload errors.
  • Source file issues: invalid format, zero-sized or over-sized file, bad file name, too long URLs.
  • Invalid target format provided for the format of the source file.
  • Not having enough credits to convert the source file.


conv_query
Description Query the status of the conversion for a single file.
Note: It's recommended to send this request repetitively every (3 to 10) seconds until you get a response indicating the conversion is done. Calling it too much abuses the request rate causing your secret key to get blocked, and calling it too few will make the system think your app has frozen, causing your request to be removed from the queue.
Method GET, POST
Parameters
  • func: conv_query
  • secretkey: (Your secret key)
  • conv_id: (The Conversion ID, from conv_init)
  • queue_id: (The Queue ID, from conv_setsource)
  • [Optional] sandbox: 1 (Send the value of 1 to indicate you want "sandbox" (testing) mode.
    This parameter should be the same as the ones sent to the conv_init and conv_setsource requests.
Response
  • retcode: [Numeric] 0 (success) or 1 (failure)
  • retdata:
    • On success: JSON object:
      • status: [Numeric] 0 (Queued), 1 (Converting), 2 (Done).
      • ahead: [Numeric] Only meaningful when status equals 0 (Queued)
        Indicates number of users ahead of you in the queue.
      • conv_results: [JSON] Exists only when status equals 2 (Done)
        consists of:
        • success: [Numeric-Boolean] 0 (conversion failed), 1 (conversion succeeded).
          Note: When success equals 0 (failed), the credits needed for conversion (which were indicated in conv_setsource response) will be refunded to you. No credits are consumed unless you get a success with value of 1.
        • issue_info: [String] Only when success equals 1 (succeeded), but there is some issue with the source file.
          Contains a message about the issue incountered while converting. (full message).
        • issue_mini: [String] Same as issue_info: when success equals 1 but with issues with the source file.
          Contains a mini-message (1 or 2 words) about the issue. (can be ignored).
        • error_str: [String] Only when success equals 0 (failed)
          Contains an error message.
        • download_link: [String] Only when success equals 1 (succeeded)
          Contains a fully-qualified URL link to download the converted file (with all the required parameters).
    • On failure: [String] The error message.
Possible causes of failure
  • An invalid secret key.
  • Mismatched converison mode ("sandbox" or "real") between conv_init, conv_setsource, and conv_query.
  • Invalid conv_id or queue_id.
  • Expired file. (Refer to FileZigZag privacy policy to learn about how much time converted files are kept).


Notes