Convert API v1

Upload files and convert between formats. Also list supported conversions, detect file types and more.

Contents

Base URL & Authentication
POST /upload
POST /convert
Full Conversion Flow
Optional: POST /list_ext_out_by_type
Optional: POST /list_ext_out
Optional: POST /detect_file_type

Base URL & Authentication

Base URL

[% base_url %]/api/v1

Authentication

Every request includes the Api-Key header. On the server side it is read as HTTP_API_KEY from the request environment:

Api-Key: YOUR_API_KEY

Common Request Headers

Header	Value	Notes
`Api-Key`	Your secret key	Sent with every request. If not included default usage limits apply (aka testing only).
`Accept`	`application/json`	Requested for all endpoints

Common Response

All endpoints return JSON with a Status field:

"Status": "OK"      // success
"Status": "Error"   // failure — see Message field

POST /upload

Upload a file to the server. Returns a server-side filename used for subsequent operations.

POST/api/v1/upload

Request — `multipart/form-data`

Field	Type	Description
`file`	file	The file to upload required

Response

{
  "Status":   "OK",
  "Filename": "1776928056_sample.png"
}

Save the Filename value — you will need it for /convert.

curl

curl -s -X POST [% base_url %]/api/v1/upload \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -F "[email protected]"

Perl

use HTTP::Request::Common qw(POST);

my $req = POST(
  "$api_base/upload",
  Content_Type => 'form-data',
  Content      => [ file => ['/path/to/sample.png'] ],
);
$req->header('Api-Key' => 'YOUR_API_KEY');
$req->header(Accept    => 'application/json');
my $res = $ua->request($req);

POST /convert

Convert a previously uploaded file to a new format.

POST/api/v1/convert

Request — `application/json`

Field	Type	Description
`filename`	string	Server-side filename from `/upload` required
`ext_in`	string	Source extension (e.g. `"png"`) required
`ext_out`	string	Target extension (e.g. `"gif"`) required

Response

{
  "file": {
    "ext_out": "gif",
    "urls": ["/tmp/1776928056_sample.gif"]
  }
}

curl

curl -s -X POST [% base_url %]/api/v1/convert \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"filename":"1776928056_sample.png","ext_in":"png","ext_out":"gif"}'

Perl

my $payload = {
  filename => '1776928056_sample.png',
  ext_in   => 'png',
  ext_out  => 'gif',
};

my $req = HTTP::Request->new(POST => "$api_base/convert");
$req->header('Api-Key'      => 'YOUR_API_KEY');
$req->header(Accept         => 'application/json');
$req->header('Content-Type' => 'application/json');
$req->content(encode_json($payload));
my $res = $ua->request($req);

Full Conversion Flow

A typical end-to-end workflow looks like this:

List (Optional) — Call /list_ext_out_by_type to discover which output formats are available for your source file type.
Upload — Call /upload with the file; receive a server-side filename.
Convert — Call /convert with the server filename and desired ext_out; receive a download URL.
Download — GET a file from download URL.

curl — complete example

# 1. (Optional) List available output formats for a PNG
curl -s -X POST [% base_url %]/api/v1/list_ext_out_by_type \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"ext_in":"png"}'

# 2. Upload the file
curl -s -X POST [% base_url %]/api/v1/upload \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -F "[email protected]"

# 3. Convert (use Filename from step 2)
curl -s -X POST [% base_url %]/api/v1/convert \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"filename":"1776928056_sample.png","ext_in":"png","ext_out":"gif"}'

# 4. Download resulting file (use Download link from step 3)
  curl [% base_url %]/tmp/1776928056_sample.gif

Perl — complete example

use strict;
use warnings;
use HTTP::Request;
use HTTP::Request::Common qw(POST);
use JSON::PP qw(encode_json decode_json);
use LWP::UserAgent;

my $api_base = '[% base_url %]/api/v1';
my $api_key  = 'YOUR_API_KEY';
my $ua       = LWP::UserAgent->new(timeout => 20);

# 1. List available output formats
my $req = HTTP::Request->new(POST => "$api_base/list_ext_out");
$req->header('Api-Key'      => $api_key);
$req->header(Accept         => 'application/json', 'Content-Type' => 'application/json');
$req->content(encode_json({ ext_in => 'png' }));
my $list = decode_json($ua->request($req)->decoded_content);
print "Available: @{$list->{extensions}}\n";

# 2. Upload
$req = POST("$api_base/upload",
  Content_Type => 'form-data',
  Content      => [ file => ['sample.png'] ],
);
$req->header('Api-Key' => $api_key);
$req->header(Accept    => 'application/json');
my $upload = decode_json($ua->request($req)->decoded_content);
my $srv_name = $upload->{Filename};
print "Uploaded as: $srv_name\n";

# 3. Convert
$req = HTTP::Request->new(POST => "$api_base/convert");
$req->header('Api-Key'      => $api_key);
$req->header(Accept         => 'application/json', 'Content-Type' => 'application/json');
$req->content(encode_json({
  filename => $srv_name, ext_in => 'png', ext_out => 'gif',
}));
my $conv = decode_json($ua->request($req)->decoded_content);
print "Converted: $conv->{file}{urls}[0]\n";

Optional: POST /list_ext_out_by_type

Get available output extensions grouped by file type category (image, document, audio, video, etc.).

POST/api/v1/list_ext_out_by_type

Request — `application/json`

Field	Type	Description
`ext_in`	string	Source file extension (e.g. `"png"`) required

Response

{
  "Status": "OK",
  "extensions_by_type": {
    "document": { "pdf": 1, "ps": 1, "docx": 0, "html": 0, "rtf": 0 },
    "ebook":   { "epub": 1, "fb2": 1, "mobi": 1 },
    "image":   { "gif": 1, "jpg": 1, "png": 1, "bmp": 1, "svg": 1, "tiff": 1, "webp": 0 },
    "text":    { "txt": 1 }
  },
  "menu_popular": [{ "image": ["jpg","png","gif","tiff","svg"] },
                    { "document": ["pdf","docx"] }],
  "type": "image"
}

Each extension inside extensions_by_type has a value of 1 (supported / recommended) or 0 (available but not primary). Use menu_popular for quick UI rendering.

curl

curl -s -X POST [% base_url %]/api/v1/list_ext_out_by_type \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"ext_in":"png"}'

Perl

my $req = HTTP::Request->new(POST => "$api_base/list_ext_out_by_type");
$req->header('Api-Key'      => 'YOUR_API_KEY');
$req->header(Accept         => 'application/json');
$req->header('Content-Type' => 'application/json');
$req->content(encode_json({ ext_in => 'png' }));
my $res = $ua->request($req);

Optional: POST /list_ext_out

Get a flat list of output extensions available for a given input extension.

POST/api/v1/list_ext_out

Request — `application/json`

Field	Type	Description
`ext_in`	string	Source file extension (e.g. `"png"`) required

Response

{
  "Status": "OK",
  "extensions": ["gif", "jpg", "bmp", "pdf", "svg", "tiff", "txt", "epub"]
}

curl

curl -s -X POST [% base_url %]/api/v1/list_ext_out \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"ext_in":"png"}'

Perl

my $req = HTTP::Request->new(POST => "$api_base/list_ext_out");
$req->header('Api-Key'      => 'YOUR_API_KEY');
$req->header(Accept         => 'application/json');
$req->header('Content-Type' => 'application/json');
$req->content(encode_json({ ext_in => 'png' }));
my $res = $ua->request($req);

Optional: POST /detect_file_type

Detect the true file type by examining the file's extension, size, MIME type, filename, and its first bytes. The payload uses a custom binary format with fields separated by 0xFE.

POST/api/v1/detect_file_type

Request — `application/octet-stream`

The body is built by joining five fields with the byte 0xFE:

ext \xFE size_hex \xFE mimetype \xFE filename \xFE first_bytes

Segment	Description	Example
`ext`	Lowercase file extension	`png`
`size_hex`	File size in hexadecimal	`43B`
`mimetype`	Guessed MIME type	`image/png`
`filename`	Original file name (basename)	`sample.png`
`first_bytes`	Up to 200 raw bytes from the start of the file	(binary)

Response

Returns plain text (or HTML) describing the detected file type. Content-Type is text/plain; charset=utf-8.

This is a PNG file! The file type is a Portable Network Graphics image
by PNG Development Group / W3C.

curl (conceptual)

# Build the binary payload first with Perl, then POST it:
perl -e '
  my $file = "sample.png";
  open my $fh, "<:raw", $file;
  read($fh, my $bytes, 200);
  close $fh;
  my $body = join("\xFE", "png", sprintf("%X", -s $file), "image/png", $file, $bytes);
  open my $out, ">:raw", "/tmp/detect.bin";
  print {$out} $body;
  close $out;
'

curl -s -X POST [% base_url %]/api/v1/detect_file_type \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Accept: text/plain, application/json" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @/tmp/detect.bin

Perl

my $file = 'sample.png';
open my $fh, '<:raw', $file;
read($fh, my $first_bytes, 200);
close $fh;

my $payload = join("\xFE",
  'png',                              # ext
  sprintf('%X', -s $file),              # size_hex
  'image/png',                         # mimetype
  'sample.png',                        # filename
  $first_bytes,                        # first bytes
);

my $req = HTTP::Request->new(POST => "$api_base/detect_file_type");
$req->header('Api-Key'      => 'YOUR_API_KEY');
$req->header(Accept         => 'text/plain, application/json');
$req->header('Content-Type' => 'application/octet-stream');
$req->content($payload);
my $res = $ua->request($req);

Base URL & Authentication

Base URL

Authentication

Common Request Headers

Common Response

POST /upload

Request — multipart/form-data

Response

curl

Perl

POST /convert

Request — application/json

Response

curl

Perl

Full Conversion Flow

curl — complete example

Perl — complete example

Request — application/json

Response

curl

Perl

Request — application/json

Response

curl

Perl

Request — application/octet-stream

Response

curl (conceptual)

Perl

Request — `multipart/form-data`

Request — `application/json`

Request — `application/json`

Request — `application/json`

Request — `application/octet-stream`