TransConvert API

Üç adımda sıfırdan ilk dönüştürülmüş dosyanıza.

Her istek, Authorization başlığında Bearer token olarak gönderilen bir API anahtarı gerektirir.

Basic, Lite, Pro ve Team planlarında kullanılabilir. Hesabınızdan bir anahtar oluşturun →

Anahtarınızı test edin

Gerçek bir entegrasyon kodu yazmadan önce bir anahtarın çalıştığını doğrulamanın hızlı bir yolu — bu tek başına hiçbir şeyi dönüştürmez (ekli dosya yok), ama 401 yerine 400 no_file alınması anahtarın geçerli olduğunu doğrular.

Tek bir uç nokta tüm dönüştürmeleri karşılar. Dosyanız ve aşağıdaki alanlarla birlikte bir multipart/form-data POST isteği gönderin.

Parametreler

Sık kullanılan dönüştürmeler

Popüler dosya çiftleri için hızlı bir referans — aynı uç nokta, yalnızca farklı bir category/target kombinasyonuyla hepsini karşılar.

Yanıt

Başarılı olduğunda (200): dönüştürülmüş dosyanın ham baytları, buna uygun Content-Type ve Content-Disposition başlıklarıyla birlikte döner. Başarısız olduğunda: {"error": {"code": "...", "message": "..."}} şeklinde bir JSON gövdesi, eşleşen bir HTTP durum koduyla birlikte döner — aşağıdaki Hatalar bölümüne bakın.

Bir dosyayı formatını değiştirmeden küçültün — girişte ve çıkışta aynı format. Dönüştürmeden ayrı, kendi seçenekleri aşağıda verilen iki kategori: image-compress ve document-compress.

image-compress

Girişte ve çıkışta aynı format (JPG/PNG/WEBP/GIF) — target_percent, sonucun orijinale göre ne kadar küçük olmayı hedeflediğidir, sabit bir kalite ayarı değildir.

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

Girişte ve çıkışta PDF, Ghostscript'in kendi yeniden sıkıştırmasıyla — yüklenenden daha büyük bir dosya asla döndürmez (yeniden sıkıştırma işe yaramazsa orijinale geri döner).

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 ve ses dönüştürmeleri dakikalarca sürebilir — tek bir senkron isteği bu kadar uzun süre açık tutmak pratik değildir, bu yüzden yukarıdaki uç nokta yerine gönder-sonra-sorgula akışı kullanılır. Bir dosya gönderin, hemen bir job_id alın, ardından işiniz tamamlanana kadar durumunu sorgulayın.

Bir iş gönderin

Ana uç noktayla aynı multipart POST biçimi, farklı bir URL'de.

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"

Yanıt (202 Accepted)

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

Durumu sorgulayın

Aldığınız job_id ile bunu birkaç saniyede bir sorgulayın. "status" alanı queued, processing, completed veya failed değerlerinden biridir.

{
  "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'lar (isteğe bağlı)

Gönderim sırasında bir webhook_url verdiyseniz, iş bittiğinde — başarılı ya da başarısız — bu aynı JSON gövdesini oraya bir kez POST ederiz; uç noktanız yanıt vermezse birkaç kez tekrar deneriz. job-status.php yine de bir yedek olarak çalışmaya devam eder.

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

Sonucu indirin

"status" "completed" olduğunda yanıt bir download_url içerir — aynı durum URL'sine &download=1 eklenmiş hali. Bu URL'e istek atmak, sayfadaki diğer tüm uç noktalarla aynı başlıklarla dönüştürülmüş dosyanın ham baytlarını akıtır. Sonuç, indirildiği anda silinir; hiç indirilmezse kısa bir saklama süresinin ardından otomatik olarak silinir.

scheduleİş sonuçları indirildikten hemen sonra silinir; hiç indirilmezse kısa bir saklama süresinin ardından otomatik olarak silinir — dosyanızı zamanında indirin.

Aynı istek dört dilde — kendi teknoloji yığınınıza uyanı seçin. Her biri yerel bir photo.jpg dosyasını PNG'ye dönüştürüp sonucu kaydeder.

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

Her başarısızlık, kodunuzun dallanabileceği bir "code" ile birlikte insan tarafından okunabilir bir "message" içeren bir JSON hata zarfı döndürür. Bazı hatalar ek alanlar içerir (örneğin quota_exceeded, "limit" ve "used" içerir).

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

Hataları ve yeniden denemeleri yönetme

JSON'daki "code" alanına göre dallanın, "message" metnine göre değil — ifade zamanla değişebilir, kod değişmez. concurrency_limit, birkaç saniye sonra kısa bir yeniden deneme için uygundur (devam eden dönüştürmelerinizden biri bittiği anda ortadan kalkar); quota_exceeded gelecek aya kadar kendiliğinden çözülmez, bu yüzden bir döngüde tekrar tekrar denemeyin. conversion_failed, HTTP durumunun hâlâ önemli olduğu tek koddur: 503 kısa bir yeniden denemeye değer geçici bir sunucu tarafı sorunudur, 400/415/422/500 ise o dosya/hedef kombinasyonunun kaç kez yeniden gönderirseniz gönderin başarılı olmayacağı anlamına gelir. Yüklemeden önce bir dosyanın boyutunu istemci tarafında kontrol etmek, kesin bir file_too_large için isteği boşa harcamayı önler.

API, web sitesinde zaten kullandığınız planla aynı limitleri paylaşır — ayrıca yapılandırılacak bir şey yoktur.

Dakika başına bir sınır uygulandığında her yanıt X-RateLimit-Limit ve X-RateLimit-Remaining başlıklarını içerir; 429 yanıtında ayrıca Retry-After (saniye) de bulunur — sınıra çarpmadan önce yavaşlamak için bunları kullanın.

Web sitesinin kullandığı ile tamamen aynı dönüştürme motoru — hiçbir şey yalnızca API'ye veya yalnızca web sitesine özel değildir.

infoVideo ve ses — hem dönüştürme hem sıkıştırma — şimdilik yalnızca web sitesinde kullanılabilir: eş zamanlı bir HTTP çağrısı, birkaç dakika sürebilen bir iş için uygun değildir.