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.
-
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:
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.
-
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".
-
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.
-
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.
-
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:
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).
-
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:
- Don't forget to put in your secret key instead of XXX-XXXXXXX before running the application.
- Source codes are in the public domain. Feel free to download and modify/test them as you like.
-
Sample apps demonstrate how to work with the requests in a very simple way. They may not provide the best practice regarding security or performance. It's your
responsibility to modify them in the way you find useful.
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 Size | Credit 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:
- All requests need the func and secretkey parameters.
- Responses are JSON-encoded strings that consist of at least retcode and retdata members.
-
Always check the value of retcode before using the data in retdata member, because often
retcode determines the data format of the retdata member.
- There are a lot of cases that can produce errors. Most of them are mentioned in the "Possible causes for failure", but there might be more. Always
check the response members carefully.
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 |
|
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
-
Don't abuse requests. Call the API only as needed. Query conversion status (using conv_query request) on (3 to 10 seconds)
intervals.
Note: If you send too much requests, the system may automatically block your secret key!
-
Uploaded and converted user files has the same privacy and lifetime that applies to FileZigZag.com user files. Refer to FileZigZag.com's privacy policy for
more information.
-
You can send and convert one file at a time. Send conv_permitted request to check if you can send the next file or start a new
conversion.
-
Note that the sample applications provided in this page are just examples. They don't include the best development practices. Also, they don't make use of the
conv_permitted request, but you should do so in productive applications.
-
Take care of your secret keys. Network requests can be monitored and sensitive data may got stolen. You are responsible of keeping your secret key
hidden and not easily monitored or accessed. For example, by implementing a proxy script that redirects your requests and add your secret key to the requests
before they reach our API.
-
When using the "Sandbox" mode, the resulting file may not match the needed "target format". (because it's not a real conversion).
-
"credit_cost" member returned with a successful conv_setsource request means how much credits were deducted from your account,
not how it will cost. So, this value is always 0 when you choose "Sandbox" mode. Therefore it cannot be used to find out how much credits a file will cost.
Please refer to the Credit cost section to learn more about credit costs.