TransConvert API

Dari nol hingga file konversi pertama Anda dalam tiga langkah.

Setiap permintaan memerlukan kunci API, yang dikirim sebagai Bearer token di header Authorization.

Tersedia di paket Basic, Lite, Pro, dan Tim. Buat kunci dari akun Anda →

Uji kunci Anda

Cara cepat memastikan kunci Anda berfungsi sebelum menulis kode integrasi sesungguhnya — permintaan ini sendiri tidak mengonversi apa pun (tidak ada file terlampir), tetapi respons 400 no_file (bukan 401) sudah memastikan kunci itu sendiri valid.

Satu endpoint menangani semua konversi. Kirim permintaan POST multipart/form-data berisi file Anda beserta kolom-kolom di bawah ini.

Parameter

Konversi umum

Referensi cepat untuk pasangan format populer — endpoint yang sama menangani semuanya, hanya dengan kombinasi category/target yang berbeda.

Respons

Jika berhasil (200): byte mentah file hasil konversi, dengan header Content-Type dan Content-Disposition yang sesuai. Jika gagal: isi JSON berbentuk {"error": {"code": "...", "message": "..."}} dengan kode status HTTP yang sesuai — lihat bagian Kesalahan di bawah.

Perkecil ukuran file tanpa mengubah formatnya — format masuk sama dengan format keluar. Ini adalah pasangan kategori terpisah dari konversi, yaitu image-compress dan document-compress, masing-masing dengan opsinya sendiri di bawah.

image-compress

Format masuk sama dengan format keluar (JPG/PNG/WEBP/GIF) — target_percent menentukan seberapa kecil hasil yang ditargetkan relatif terhadap file asli, bukan pengaturan kualitas tetap.

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 masuk, PDF keluar, melalui pemampatan ulang milik Ghostscript sendiri — tidak akan pernah mengembalikan file yang lebih besar dari yang diunggah (kembali ke file asli jika pemampatan ulang tidak membantu).

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

Konversi video dan audio bisa berjalan selama beberapa menit — terlalu lama untuk mempertahankan satu permintaan sinkron tetap terbuka — sehingga menggunakan alur submit-lalu-poll, bukan endpoint di atas. Kirim sebuah file, dapatkan job_id sebagai balasan langsung, lalu poll statusnya sampai selesai.

Kirim tugas

Bentuk POST multipart yang sama seperti endpoint utama, hanya di URL yang berbeda.

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"

Respons (202 Accepted)

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

Poll status

Poll endpoint ini setiap beberapa detik menggunakan job_id yang Anda terima. "status" berupa salah satu dari queued, processing, completed, atau 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"
}

Webhook (opsional)

Jika Anda memberikan webhook_url saat mengirim, kami akan mem-POST isi JSON yang sama ke sana satu kali setelah job selesai — berhasil atau gagal — mencoba beberapa kali lagi jika endpoint Anda tidak merespons. job-status.php tetap berfungsi sebagai cadangan.

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"
}

Unduh hasilnya

Setelah status menjadi "completed", respons menyertakan download_url — URL status yang sama dengan tambahan &download=1. Meminta URL ini akan menstream byte mentah file hasil konversi, dengan header yang sama seperti endpoint lain di halaman ini. Hasil akan dihapus begitu diunduh, atau otomatis dihapus setelah periode penyimpanan singkat jika tidak pernah diunduh.

scheduleHasil tugas dihapus segera setelah diunduh, atau otomatis dihapus setelah periode penyimpanan singkat jika tidak pernah diunduh — segera unduh.

Permintaan yang sama dalam empat bahasa pemrograman — pilih yang sesuai dengan stack Anda. Masing-masing mengonversi file lokal photo.jpg ke PNG lalu menyimpan hasilnya.

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());
    }
}

Setiap kegagalan mengembalikan bungkus kesalahan JSON berisi "code" yang dapat digunakan kode Anda untuk pencabangan logika, ditambah "message" yang mudah dibaca manusia. Beberapa kesalahan menyertakan kolom tambahan (misalnya, quota_exceeded menyertakan "limit" dan "used").

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

Menangani kesalahan & percobaan ulang

Gunakan kolom JSON "code" untuk pencabangan logika, bukan teks "message" — kata-katanya bisa berubah seiring waktu, kodenya tidak. concurrency_limit layak dicoba ulang sebentar setelah beberapa detik (kondisi ini hilang begitu salah satu konversi Anda yang sedang berjalan selesai); quota_exceeded tidak akan pulih dengan sendirinya sampai bulan berikutnya, jadi jangan mencoba ulang dalam sebuah loop. conversion_failed adalah satu-satunya kode di mana status HTTP masih penting: 503 adalah masalah sementara di sisi server yang layak dicoba ulang sekali secara singkat, sedangkan 400/415/422/500 berarti kombinasi file/target tersebut tidak akan pernah berhasil sebanyak apa pun Anda mengirim ulang. Memeriksa ukuran file di sisi klien sebelum mengunggah akan menghindarkan Anda dari permintaan yang sia-sia karena sudah pasti akan menghasilkan file_too_large.

Batas API mengikuti paket yang sama dengan yang Anda gunakan di situs web — tidak ada konfigurasi terpisah yang diperlukan.

Setelah batas per menit berlaku, setiap respons menyertakan header X-RateLimit-Limit dan X-RateLimit-Remaining; respons 429 juga menyertakan Retry-After (dalam detik) — gunakan ini untuk memperlambat sebelum mencapai batas, alih-alih baru bereaksi setelah menerima 429.

Menggunakan mesin konversi yang persis sama dengan situs web — tidak ada yang eksklusif untuk API atau eksklusif untuk situs web.

infoVideo dan audio — baik konversi maupun kompresi — untuk saat ini hanya tersedia di situs web: panggilan HTTP sinkron kurang cocok untuk proses yang bisa memakan waktu beberapa menit.