Documentation
File Conversion API
Download Samples (C#, node.js, PHP, Shell)

Getting Started

This tutorial will show you how to use the twistfile.com API to convert a file. There are only three short steps involved:
  1. Obtain an API Key
  2. Start Conversion Job
  3. Check Result State
  4. Download Converted Files
  5. Reference



1. Obtain an API key.


Every request to the twistfile.com API must include a API Key, so that we can identify you. Once you have signed up for an account, you can get your API Key.



2. Start Conversion Job


To convert a file with twistfile.com, you need to send a request to the jobs endpoint. Note that this is a multi-part request. The first part contains binary data (your image file) while the other part contains typical POST data: a key-value pair.

2.1 Convert Single File.

Request

  • Shell
  • Node.js
  • C#
  • PHP

curl -k https://twistfile.com/api/job \
 -X POST \
 -F "key=GdG2OsY2LOGMUDdMgPBz" \
 -F "source_file=@/home/mike/Desktop/price.xls" \
 -F "target=jpeg" \
 -F "out_format=xml" \
 -F "density=200" \
 -F "background=white"
	

var request = require('request');
var fs = require('fs');

var req = request.post({url:"https://twistfile.com/api/job"}, function (err, resp, body) {
  if (err) {
        console.error('Unable to start conversion job', err);
  } else {
    console.log(JSON.parse(body));
    var respJSON = JSON.parse(body);
    console.log(respJSON.error.code + ": " + respJSON.error.message);
    console.log("Job ID: " + respJSON.job.id);
  }
});

var form = req.form();
form.append("target", "jpeg");
form.append("key", "GdG2OsY2LOGMUDdMgPBz");
form.append("out_format", "json");
form.append("density", "200");
form.append("background", "white");
form.append("source_file", fs.createReadStream('/home/mike/Desktop/price.xls'));
	

const string urlJob = "https://twistfile.com/api/job";
const string apiKey = "GdG2OsY2LOGMUDdMgPBz";                   //!!! use your own key
const string fileName = "c:\\tmp\\price.xls";

//send job
string xmlString = Upload(apiKey, urlJob, fileName, "jpeg").Result;
//xml result
XmlDocument doc = new XmlDocument();
doc.LoadXml(xmlString);

static async Task Upload(string apiKey, string url, string sourceFile, string sTarget)
{
	using (HttpClientHandler handler = new HttpClientHandler())
	using (HttpClient client = new HttpClient(handler))
	{
		var request = new MultipartFormDataContent();

		request.Add(new StringContent(apiKey), "key");
		request.Add(new StringContent(sTarget), "target");
		request.Add(new StringContent("xml"), "out_format");
		request.Add(new StreamContent(File.OpenRead(sourceFile)), "source_file", new FileInfo(sourceFile).Name);

		using (HttpResponseMessage response = await client.PostAsync(url, request).ConfigureAwait(false))
		using (HttpContent content = response.Content)
		{
			string data = await content.ReadAsStringAsync();
			return data;
		}
	}
}
	

<?php
	$apiUrl = 'https://twistfile.com/api/job';
	$imagePath = '/home/mike/Desktop/price.xls';
	$apiKey = 'GdG2OsY2LOGMUDdMgPBz';

	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, $apiUrl);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_POST, true);
	curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-type: multipart/form-data"));

	$post_array = array(
		'key'=>$apiKey,
		'target'=>'jpeg',
		'source_file'=>curl_file_create($imagePath),
		//'source_file'=>"@$imagePath",
		//'out_format'=>'json',
		'density'=>200,
		'background'=>'white'
	);

	curl_setopt($ch, CURLOPT_POSTFIELDS, $post_array);
	$data = curl_exec($ch);

	$header_str = curl_getinfo($ch, CURLINFO_CONTENT_TYPE);
	curl_close($ch);

	header("Content-type: " . $header_str);
	echo $data;
?>
	

Response

The response contains the job ID, status of the new job ("error" node), and confirms the some parameters included in your request.

  • XML
  • JSON

<twistfile version='1.1'>
	<error code='1001'>Info. in queue<error>
	<job id='8576' key='GdG2OsY2LOGMUDdMgPBz' queue='1' start_time='2017-11-21-17-39-56' stop_time='' />
	<source_file name='price.xls' />
</twistfile>
	

{
  "version":"1.1",
  "error": {
     "code":1001, 
     "message":"Info. in queue"
  },
  "job": { 
     "id":8576, 
     "key":"GdG2OsY2LOGMUDdMgPBz", 
     "queue":0, 
     "start_time":"2017-11-21-17-48-58",
     "stop_time":""
   },
  "source_file":{"name":"price.xls"}
}
	

twistfile.com is now converting your file.

2.2 Convert Files Package (linked jobs).

You can send jobs with delayed processing. To do that, set the "linked=yes" parameter for the first file called master file. Remember the job ID of the file to be able to specify that the current file is associated with this master file (for example "linked=8583") when sending subsequent files in the batch. To start processing a batch of files, send a request with the job ID of the master file. Batch processing will start immediately. Processing of a batch of files is different from the processing of a single file. For example, if your package has several JPEG files, and the target format of the master file is PDF, then all the JPEG files will be merged into a single PDF.

Request

  • Shell

# 1. send first (master) file
curl -k https://twistfile.com/api/job \
 -X POST \
 -F "key=GdG2OsY2LOGMUDdMgPBz" \
 -F "source_file=@/home/mike/Desktop/price.xls" \
 -F "target=pdf" \
 -F "out_format=xml" \
 -F "linked=yes"

# 2. send second file
curl -k https://twistfile.com/api/job \
 -X POST \
 -F "key=GdG2OsY2LOGMUDdMgPBz" \
 -F "source_file=@/home/mike/Desktop/app.pdf" \
 -F "out_format=xml" \
 -F "linked=8583"

# 3. send third file
curl -k https://twistfile.com/api/job \
 -X POST \
 -F "key=GdG2OsY2LOGMUDdMgPBz" \
 -F "source_file=@/home/mike/Desktop/image-1.jpg" \
 -F "out_format=xml" \
 -F "linked=8583"

# 4. start linked jobs conversion
curl -k https://twistfile.com/api/job \
 -X POST \
 -F "key=GdG2OsY2LOGMUDdMgPBz" \
 -F "out_format=xml" \
 -F "linked=8583"
	

Response

  • XML
  • JSON

<!-- Response after point 1 (first file) -->
<twistfile version='1.1'>
	<error code='1003'>Info. delayed</error>
	<job id='8583' key='GdG2OsY2LOGMUDdMgPBz' queue='0' start_time='2017-11-21-18-36-54' stop_time='' />
	<source_file name='price.xls' >
<twistfile>

<!-- Response after point 2 -->
<twistfile version='1.1'>
	<error code='1003'>Info. delayed<error>
	<job id='8584' key='GdG2OsY2LOGMUDdMgPBz' queue='0' start_time='2017-11-21-18-43-13' stop_time='' />
	<source_file name='app.pdf' />
<twistfile>

<!-- Response after point 3 -->
<twistfile version='1.1'>
	<error code='1003'>Info. delayed</error>
	<job id='8585' key='GdG2OsY2LOGMUDdMgPBz' queue='0' start_time='2017-11-21-18-44-13' stop_time='' />
	<source_file name='image-1.jpg' >
</twistfile>

<!-- Response after point 4 -->
<twistfile version='1.1'>
	<error code='1001'>Info. in queue</error>
	<job id='8583' key='GdG2OsY2LOGMUDdMgPBz' queue='0' start_time='2017-11-21-18-44-34' stop_time='' />
	<source_file name='' /v
<twistfile>
	


{
  "version":"1.1",
  "error": {
    "code":1003,
    "message":"Info. delayed"
  },
  "job": {
    "id":8583,
    "key":"GdG2OsY2LOGMUDdMgPBz", "queue":0, "start_time":"2017-11-21-19-09-00", "stop_time":""
  },
  "source_file":{"name":"price.xls"}
}

{
  "version":"1.1",
  "error": {
    "code":1003, 
    "message":"Info. delayed"
  },
  "job": {
    "id":8584,
    "key":"GdG2OsY2LOGMUDdMgPBz", "queue":0, "start_time":"2017-11-21-19-09-43", "stop_time":""
  },
  "source_file":{"name":"app.pdf"}
}

{
  "version":"1.1",
  "error": {
    "code":1003,
    "message":"Info. delayed"
  },
  "job": {
    "id":8585,
    "key":"GdG2OsY2LOGMUDdMgPBz", "queue":0, "start_time":"2017-11-21-19-10-01", "stop_time":""
  },
  "source_file":{"name":"image-1.jpg"}
}

{
  "version":"1.1",
  "error": {
    "code":1001,
    "message":"Info. in queue"
  },
  "job": {
    "id":8583,
    "key":"GdG2OsY2LOGMUDdMgPBz", "queue":0, "start_time":"2017-11-21-19-10-17", "stop_time":""
  },
  "source_file":{"name":""}
}
	




3. Check Result State


  • POST
  • GET
URL
https://twistfile.com/api/job
  • key - your API Key
  • id - Job ID
  • out_format - format of output, "xml" or "json", default - "xml"
  • del_result - delete result, "yes" or "no", default - "no". next time the "result" node of response will be empty
https://twistfile.com/api/API_KEY/JOB_ID

https://twistfile.com/api/API_KEY/JOB_ID/xml

https://twistfile.com/api/API_KEY/JOB_ID/json

https://twistfile.com/api/API_KEY/JOB_ID/json?del_result=yes

https://twistfile.com/api/API_KEY/JOB_ID?del_result=yes

Before you can access the converted files, you should check to see whether your job has finished successfully, by sending a GET or POST request. In this request, you’ll need to use the Job ID returned by twistfile.com when you created your job. Once your job has completed successfully, the response "error code" will "0" and "files" contains IDs. Please do not check the job state instantly after conversion has been started. Depending of your jobs the server requires 5..30 or more seconds to complete the job, try to call the first checking after 5..10 seconds.

Request

  • Shell
  • Node.js
  • C#
  • PHP

curl -k https://twistfile.com/api/job \
 -X POST \
 -F "id=8590" \
 -F "out_format=xml" \
 -F "key=GdG2OsY2LOGMUDdMgPBz"
	

var request = require('request');

apiKey = "GdG2OsY2LOGMUDdMgPBz";
jobID = 8590;

var req = request.get({url:"https://twistfile.com/api/"+apiKey+"/"+jobID+"/json"}, function (err, resp, body) {
  if (err) {
        console.error('Unable to start conversion job', err);
  } else {
    var respJSON = JSON.parse(body);
    console.log(respJSON);
    if (respJSON.error.code == 0) {
      for (i=0; i < respJSON.result.files.length; ++i) {
        console.log(respJSON.result.files[i].id + ": " + respJSON.result.files[i].name);
      }
    }
  }
});
	

const string urlBase = "https://twistfile.com/api/";
const string apiKey = "GdG2OsY2LOGMUDdMgPBz";                   //!!! use your own key

int jobID = 8590;
string endpoint = urlBase + apiKey + "/" + jobID.ToString() + "/xml";
string xmlString = Query(apiKey, endpoint).Result;

XmlDocument doc = new XmlDocument();
doc.LoadXml(xmlString);

static async Task Query(string key, string url)
{
	using (HttpClientHandler handler = new HttpClientHandler())
	using (HttpClient client = new HttpClient())
	using (HttpResponseMessage response = await client.GetAsync(url).ConfigureAwait(continueOnCapturedContext: false))
	using (HttpContent content = response.Content)
	{
		string data = await content.ReadAsStringAsync();
		return data;
	}
}
	

<?php
	$apiBase = 'https://twistfile.com/api/';
	$apiKey = 'GdG2OsY2LOGMUDdMgPBz';
	$jobID = 8590;

	$xml = file_get_contents($apiBase . $apiKey. "/" . $jobID . "/xml");

	header('Content-Type: text/xml');
	print $xml;
?>
	

Response

  • XML
  • JSON

<twistfile version='1.1'>
	<error code='0'>Ok</error>
	<job id='8590' key='GdG2OsY2LOGMUDdMgPBz' queue='-1' start_time='2017-11-21-19-39-47' stop_time='2017-11-21-19-39-52' />
	<source_file name='Descr.docx' />
	<credit_cost cost='1' credit='3062' />
	<result>
		<files qty='5'>
			<file id='14362' name='Descr-1.jpg' />
			<file id='14363' name='Descr-2.jpg' />
			<file id='14364' name='Descr-3.jpg' />
			<file id='14365' name='Descr-4.jpg' />
			<file id='14366' name='Descr-5.jpg' />
		<files>
	</result>
</twistfile>
	

{
	"version":"1.1",
	"error":{"code":0, "message":"Ok"},
	"job":{"id":8590, "key":"GdG2OsY2LOGMUDdMgPBz", "queue":-1, "start_time":"2017-11-21-19-39-47", "stop_time":"2017-11-21-19-39-52"},
	"source_file":{"name":"Descr.docx"},
	"credit_cost":{"cost":1, "credit":3062},
	"result": {
		"files":[{"id":14362, "name":"Descr-1.jpg"},
			{"id":14363, "name":"Descr-2.jpg"},
			{"id":14364, "name":"Descr-3.jpg"},
			{"id":14365, "name":"Descr-4.jpg"},
			{"id":14366, "name":"Descr-5.jpg"}]
	}
}
	




4. Download Converted Files


You should receive the ID's of the files in your job after "Step 3".You can download a single file or several files by listing their ID's separated by a comma. If you download several files at once, they will be merged into a single ZIP archive.

  • POST
  • GET
URL
https://twistfile.com/api/job
  • key - your API Key
  • fid - Download File ID
  • del_result - delete converted file, "yes" or "no", default - "no". if "yes" the file will be deleted instantly, if "no" it deleted automatically by our service after some days
https://twistfile.com/api/files/API_KEY/FILE_ID

https://twistfile.com/api/files/API_KEY/FILE_ID,FILE_ID,FILE_ID

https://twistfile.com/api/files/API_KEY/FILE_ID?del_result=yes


Request

  • Shell
  • Node.js
  • C#
  • PHP

curl -k https://twistfile.com/api/job \
 -X POST \
 -F "key=GdG2OsY2LOGMUDdMgPBz" \
 -F "fid=14362,14363,14364" \
 -L \
 -O \
 -J
	

var http = require('https');
var fs = require('fs');

apiKey = "GdG2OsY2LOGMUDdMgPBz";
fileID = 14362;
var file = fs.createWriteStream("Descr-1.jpg");


var request = http.get("https://twistfile.com/api/files/"+apiKey+"/"+fileID, function(response) {
  response.pipe(file);
});
	

const string urlBase = "https://twistfile.com/api/";
const string apiKey = "GdG2OsY2LOGMUDdMgPBz";
int fileId = 14362;
string sPathToSave = "c:\\tmp";
string sFileName = "Descr-1.jpg";

using (var client = new System.Net.WebClient())
{
	client.DownloadFile(urlBase + "files/" + apiKey + "/" + fileId.ToString(), sPathToSave + "\\" + sFileName);
}
	

<?php
	$apiBase = 'https://twistfile.com/api/';
	$apiKey = 'GdG2OsY2LOGMUDdMgPBz';
	$fileID = 14362;
	$fileName = "/home/mike/tmp/Descr-1.jpg";

	file_put_contents($fileName, fopen($apiBase . "files/" . $apiKey. "/" . $fileID, 'r'));
?>
	




5. Reference


4.1 Error/Info codes

Error CodeDescription
0Ok
1incorrect key
2cannot connect with DB
3cannot find the key
4key expired
5not enought key credit
6no source file
7file size exceed limit
8cannot move uploaded file
9upload error
10invalid file type
11cannot add job
12cannot get job
13error
14job id not found
15incorrect job id
16job id or key not found
17file size exceeds server limit
18wrong target
19cannot find result
20incorrect file ID
21cannot find file ID
22cannot open file
23cannot read file
24product/plan not found
25linked job not found
26cannot start linked job
27no target
28source-target formats incompatible
29cannot create zip
101processing. error
102processing. cannot load config
103processing. cannot parse config
104processing. cannot load source file
105cannot delete source file
106cannot create job
107DB error
200cannot set barcode decoder params
201 error during decoding
202cannot parse params
203cannot convert in RGB
204runtime barcode error
205cannot convert pdf file
1001info. in queue
1002info. processing
1003info. delayed



4.2 Parameters

ParameterDescription
Service Parameters
keyyour API Key
idJob ID
out_formatRequired format of a response.
Possible values: "xml", "json"
Default value: "xml"
del_resultDelete result.
Possible values: "yes", "no"
Default value: "no"
Image Converter Parameters
negatereplace each pixel with its complementary color
Possible values: "yes", "no"
Default value: "no"
border-widthBorder width to surround the image with a border of color
Possible values: 1...
Default value: "0"(don't surround)
border-colorborder color
Possible values: RGB value
Default value: "000000"(black)
rotateApply image rotation to the image
Possible values: integer or float value of angle in degrees
Default value: "0"(don't rotate)
contrastEnhance or reduce the image contrast
Possible values: "enhance", "reduce"
Default value: none
auto-levelAutomatically adjust color levels of image
Possible values: "yes", "no"
Default value: "no"
auto-orientadjusts an image so that its orientation is suitable for viewing (i.e. top-left orientation)
Possible values: "yes", "no"
Default value: "no"
auto-gammaAutomatically adjust gamma level of image
Possible values: "yes", "no"
Default value: "no"
qualityJPEG/MIFF/PNG compression level
Possible values: 1..100
resizeResize an image in %
Possible values: 1...100...150...
Default value: "none"
colorspaceSet the image colorspace.
Possible values: CMY, CMYK, Gray, HCL, HCLp, HSB, HSI, HSL, HSV, HWB, Lab, LCHab, LCHuv, LMS, Log, Luv, OHTA, Rec601YCbCr, Rec709YCbCr, RGB, scRGB, sRGB, Transparent, xyY, XYZ, YCbCr ,YCC, YDbDr, YIQ, YPbPr, YUV, Undefined
Default value: "none"
sketchApply sketch style.
Possible values: 50-90-100 (image threshold)
Default value: none
sketch-blursketch blur value
Possible values: 0.5 - 1 - 4.5
appendJoin images vertically or horizontally
Possible values: "vert", "horz"
Default value: "vert"
densityused when render from [Postscript, PDF, WMF, SVG] into a raster image. if multi file job, it should be in first source file settings
Possible values: 10...
Default value: "72"(72 DPI)
pagepages to processing, only for multipage files (tiff, pdf, etc.).
Possible values: "0,2", "1", "1-3", etc.
Default value: all pages
backgroundThe background color used for rendering if backgroung of the document don't defined
Possible values: blue,red, ... #ff00ff, rgb(255,0,255)
Default value: none



Most popular Office File Conversion:
XLS, DOC, XLSX, DOCX, ... -> PDF, JPEG, ...

File Merging:
DOC + PDF + XLS + JPEG + ... -> PDF, DOC, TIFF, ...

Multi page file Spliting:
DOC, PDF, TIFF, ... -> JPEG, PNG, PDF, DOC, ...

Developer API:
Embed File Conversion in your application on any platform (Windows, Linux, MAC OS, Android, ...). Don't need to install any additional software on your PC.

Our Products

Barcode Reader
www.DataSymbol.com

Barcode Reader OnLine Service
www.Reader.DataSymbol.com

Barcode Tools:
www.BarcodeTools.com

Production Online Barcode Generator:
www.bcmaker.com

Free Online Barcode Generator:
www.generator.barcodetools.com


Copyright © 1999-2017, RKD Software & RKD System Inc., All rights reserved.
All trademarks mentioned are the property of their respective owners.