TransConvert API

From zero to your first converted file in three steps.

Every request needs an API key, sent as a Bearer token in the Authorization header.

Available on the Basic, Lite, Pro, and Team plans. Generate a key from your account →

Test your key

A quick way to confirm a key works before writing any real integration code — this alone won't convert anything (no file attached), but a 400 no_file instead of a 401 confirms the key itself is valid.

A single endpoint handles every conversion. Send a multipart/form-data POST request with your file and the fields below.

Parameters

Common conversions

A quick reference for popular pairs — the same endpoint handles all of them, just with a different category/target combination.

Response

On success (200): the converted file's raw bytes, with Content-Type and Content-Disposition headers set for it. On failure: a JSON body shaped {"error": {"code": "...", "message": "..."}} with a matching HTTP status code — see Errors below.

Shrink a file without changing its format — same format in, same format out. A separate pair of categories from conversion, image-compress and document-compress, each with their own options below.

image-compress

Same format in, same format out (JPG/PNG/WEBP/GIF) — target_percent is how small the result should aim to be relative to the original, not a fixed quality setting.

curl -X POST \
  https://transconvert.com/api/v1/convert.php \
  -H "Authorization: Bearer tc_live_your_key_here" \
  -F "category=image-compress" \
  -F "target_percent=50" \
  -F "file=@photo.jpg" \
  -o compressed.jpg

document-compress

PDF in, PDF out, via Ghostscript's own recompression — never returns a file bigger than what was uploaded (falls back to the original if recompression didn't help).

curl -X POST \
  https://transconvert.com/api/v1/convert.php \
  -H "Authorization: Bearer tc_live_your_key_here" \
  -F "category=document-compress" \
  -F "level=high" \
  -F "file=@report.pdf" \
  -o compressed.pdf

Video and audio conversions can run for minutes, too long to hold open a single synchronous request — these use a submit-then-poll flow instead of the endpoint above. Submit a file, get a job_id back right away, then poll for its status until it's done.

Submit a job

Same multipart POST shape as the main endpoint, at a different URL.

curl -X POST \
  https://transconvert.com/api/v1/convert-async.php \
  -H "Authorization: Bearer tc_live_your_key_here" \
  -F "category=video" \
  -F "target=MP4" \
  -F "file=@clip.mov"

Response (202 Accepted)

{ "job_id": "job_242e1555d78d166807aa56502f15d118", "status": "queued" }

Poll for status

Poll this every few seconds with the job_id you got back. "status" is one of queued, processing, completed, or failed.

{
  "job_id": "job_242e1555d78d166807aa56502f15d118",
  "status": "completed",
  "category": "video",
  "target_format": "MP4",
  "created_at": "2026-08-26 19:17:47",
  "download_url": "/api/v1/job-status.php?job_id=job_...&download=1",
  "filename": "clip.mp4"
}

Webhooks (optional)

If you gave a webhook_url when submitting, we'll POST this same JSON body to it once the job finishes — success or failure — retrying a few times if your endpoint doesn't respond. job-status.php still works as a fallback either way.

POST your webhook_url
{
  "job_id": "job_242e1555d78d166807aa56502f15d118",
  "status": "completed",
  "category": "video",
  "target_format": "MP4",
  "created_at": "2026-08-26 19:17:47",
  "download_url": "https://transconvert.com/api/v1/job-status.php?job_id=job_...&download=1",
  "filename": "clip.mp4"
}

Download the result

Once status is "completed", the response includes a download_url — the same status URL with &download=1 appended. Requesting it then streams the converted file's raw bytes, same headers as every other endpoint on this page. The result is deleted the moment it's downloaded, or automatically after a short retention window if it's never downloaded.

scheduleJob results are deleted immediately after download, or automatically after a short retention window if never downloaded — download promptly.

The same request in four languages — pick whichever matches your stack. Each one converts a local photo.jpg to PNG and saves the result.

curl -X POST \
  https://transconvert.com/api/v1/convert.php \
  -H "Authorization: Bearer tc_live_your_key_here" \
  -F "category=image" \
  -F "target=PNG" \
  -F "file=@photo.jpg" \
  -o converted.png

<?php
$ch = curl_init('https://transconvert.com/api/v1/convert.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer tc_live_your_key_here'],
    CURLOPT_POSTFIELDS => [
        'category' => 'image',
        'target' => 'PNG',
        'file' => new CURLFile('photo.jpg'),
    ],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status === 200) {
    file_put_contents('converted.png', $response);
} else {
    $error = json_decode($response, true);
    echo $error['error']['message'];
}

const form = new FormData();
form.append('category', 'image');
form.append('target', 'PNG');
form.append('file', new Blob([fs.readFileSync('photo.jpg')]), 'photo.jpg');

const res = await fetch('https://transconvert.com/api/v1/convert.php', {
  method: 'POST',
  headers: { Authorization: 'Bearer tc_live_your_key_here' },
  body: form,
});

if (res.ok) {
  fs.writeFileSync('converted.png', Buffer.from(await res.arrayBuffer()));
} else {
  const { error } = await res.json();
  console.error(error.message);
}

import requests

with open('photo.jpg', 'rb') as f:
    response = requests.post(
        'https://transconvert.com/api/v1/convert.php',
        headers={'Authorization': 'Bearer tc_live_your_key_here'},
        data={'category': 'image', 'target': 'PNG'},
        files={'file': f},
    )

if response.status_code == 200:
    with open('converted.png', 'wb') as out:
        out.write(response.content)
else:
    print(response.json()['error']['message'])

# gem install multipart-post
require 'net/http'
require 'net/http/post/multipart'

url = URI('https://transconvert.com/api/v1/convert.php')

File.open('photo.jpg') do |file|
  req = Net::HTTP::Post::Multipart.new url,
    'category' => 'image',
    'target' => 'PNG',
    'file' => UploadIO.new(file, 'image/jpeg', 'photo.jpg')
  req['Authorization'] = 'Bearer tc_live_your_key_here'

  res = Net::HTTP.start(url.host, url.port, use_ssl: true) do |http|
    http.request(req)
  end

  if res.code == '200'
    File.write('converted.png', res.body)
  else
    puts JSON.parse(res.body)['error']['message']
  end
end

// Gradle: implementation("com.squareup.okhttp3:okhttp:4.+")
OkHttpClient client = new OkHttpClient();

RequestBody body = new MultipartBody.Builder()
    .setType(MultipartBody.FORM)
    .addFormDataPart("category", "image")
    .addFormDataPart("target", "PNG")
    .addFormDataPart("file", "photo.jpg",
        RequestBody.create(new File("photo.jpg"), MediaType.parse("image/jpeg")))
    .build();

Request request = new Request.Builder()
    .url("https://transconvert.com/api/v1/convert.php")
    .header("Authorization", "Bearer tc_live_your_key_here")
    .post(body)
    .build();

try (Response response = client.newCall(request).execute()) {
    if (response.isSuccessful()) {
        Files.write(Paths.get("converted.png"), response.body().bytes());
    } else {
        System.err.println(response.body().string());
    }
}

Every failure returns a JSON error envelope with a "code" your code can branch on, plus a human-readable "message". Some errors include extra fields (quota_exceeded includes "limit" and "used", for example).

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly API allowance of 5000 conversion-minutes reached.",
    "limit": 5000,
    "used": 5000
  }
}

Handling errors & retries

Branch on the JSON "code" field, not the "message" text — wording may change over time, the code won't. concurrency_limit is worth a short retry after a few seconds (it clears as soon as one of your in-flight conversions finishes); quota_exceeded won't resolve itself until next month, so don't retry it in a loop. conversion_failed is the one code where the HTTP status still matters: a 503 is a transient server-side issue worth one short retry, while 400/415/422/500 mean that exact file/target combination won't succeed no matter how many times you resend it. Checking a file's size client-side before uploading avoids wasting a request on a guaranteed file_too_large.

The API shares its limits with the same plan you already use on the website — nothing separate to configure.

Every response once a per-minute limit applies includes X-RateLimit-Limit and X-RateLimit-Remaining headers, and a 429 response also includes Retry-After (seconds) — use these to slow down before hitting the limit instead of only reacting after a 429.

The exact same conversion engine the website uses — nothing is API-exclusive or website-exclusive.

infoVideo and audio compression are website-only for now. Video/audio conversion is available through the API via the async submit-then-poll flow below (category "video"/"audio") rather than this single-request endpoint.