TransConvert API

In drei Schritten von null zu Ihrer ersten konvertierten Datei.

Jede Anfrage benötigt einen API-Schlüssel, der als Bearer-Token im Authorization-Header gesendet wird.

Verfügbar in den Plänen Basic, Lite, Pro und Team. Schlüssel in Ihrem Konto erstellen →

Schlüssel testen

Eine schnelle Möglichkeit, zu prüfen, ob ein Schlüssel funktioniert, bevor Sie echten Integrationscode schreiben – dies allein konvertiert nichts (keine Datei angehängt), aber ein 400 no_file statt eines 401 bestätigt, dass der Schlüssel selbst gültig ist.

Ein einzelner Endpunkt verarbeitet jede Konvertierung. Senden Sie eine multipart/form-data-POST-Anfrage mit Ihrer Datei und den unten stehenden Feldern.

Parameter

Häufige Konvertierungen

Eine schnelle Übersicht beliebter Paare – derselbe Endpunkt verarbeitet sie alle, nur mit einer anderen category/target-Kombination.

Antwort

Bei Erfolg (200): die Rohbytes der konvertierten Datei, mit entsprechend gesetzten Content-Type- und Content-Disposition-Headern. Bei einem Fehler: ein JSON-Body der Form {"error": {"code": "...", "message": "..."}} mit passendem HTTP-Statuscode – siehe „Fehler" weiter unten.

Verkleinert eine Datei, ohne ihr Format zu ändern – gleiches Format rein, gleiches Format raus. Eine eigene Gruppe von Kategorien getrennt von der Konvertierung, image-compress und document-compress, jede mit eigenen Optionen weiter unten.

image-compress

Gleiches Format rein, gleiches Format raus (JPG/PNG/WEBP/GIF) – target_percent gibt an, wie klein das Ergebnis im Verhältnis zum Original ungefähr sein soll, keine feste Qualitätseinstellung.

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 rein, PDF raus, mittels Ghostscripts eigener Rekomprimierung – liefert nie eine größere Datei als die hochgeladene zurück (fällt auf das Original zurück, falls die Rekomprimierung nichts gebracht hat).

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- und Audiokonvertierungen können mehrere Minuten dauern — zu lange, um eine einzelne synchrone Anfrage offen zu halten. Dafür wird statt des obigen Endpunkts ein Submit-dann-Poll-Ablauf verwendet: Sie senden eine Datei, erhalten sofort eine job_id zurück und fragen dann deren Status ab, bis der Vorgang abgeschlossen ist.

Auftrag einreichen

Dieselbe Multipart-POST-Struktur wie beim Haupt-Endpunkt, nur unter einer anderen 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"

Antwort (202 Accepted)

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

Status abfragen

Fragen Sie diesen Endpunkt alle paar Sekunden mit der erhaltenen job_id ab. „status" ist einer von queued, processing, completed oder 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)

Wenn Sie bei der Übermittlung eine webhook_url angegeben haben, senden wir denselben JSON-Body einmal per POST dorthin, sobald der Job fertig ist – bei Erfolg oder Fehlschlag – und versuchen es bei fehlender Antwort einige Male erneut. job-status.php funktioniert weiterhin als Fallback.

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

Ergebnis herunterladen

Sobald der Status „completed" ist, enthält die Antwort eine download_url — dieselbe Status-URL mit angehängtem &download=1. Ruft man sie auf, werden die Rohdaten der konvertierten Datei gestreamt, mit denselben Headern wie bei jedem anderen Endpunkt auf dieser Seite. Das Ergebnis wird in dem Moment gelöscht, in dem es heruntergeladen wird, oder automatisch nach einem kurzen Aufbewahrungszeitraum, falls es nie heruntergeladen wird.

scheduleAuftragsergebnisse werden sofort nach dem Herunterladen gelöscht oder automatisch nach einem kurzen Aufbewahrungszeitraum, falls sie nie heruntergeladen werden — laden Sie sie zeitnah herunter.

Dieselbe Anfrage in vier Sprachen – wählen Sie die, die zu Ihrem Stack passt. Jedes Beispiel konvertiert eine lokale photo.jpg in PNG und speichert das Ergebnis.

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

Jeder Fehler liefert einen JSON-Fehlerumschlag mit einem „code", anhand dessen Ihr Code Fallunterscheidungen treffen kann, sowie einer lesbaren „message". Manche Fehler enthalten zusätzliche Felder (quota_exceeded enthält beispielsweise „limit" und „used").

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

Umgang mit Fehlern & erneuten Versuchen

Orientieren Sie sich am „code"-Feld des JSON, nicht am „message"-Text – der Wortlaut kann sich ändern, der Code nicht. Bei concurrency_limit lohnt sich ein kurzer erneuter Versuch nach ein paar Sekunden (er verschwindet, sobald eine Ihrer laufenden Konvertierungen abgeschlossen ist); quota_exceeded löst sich erst im nächsten Monat von selbst, versuchen Sie es also nicht in einer Schleife erneut. conversion_failed ist der einzige Code, bei dem der HTTP-Statuscode weiterhin wichtig ist: Ein 503 ist ein vorübergehendes serverseitiges Problem, bei dem sich ein kurzer erneuter Versuch lohnt, während 400/415/422/500 bedeuten, dass genau diese Kombination aus Datei und Zielformat unabhängig von der Anzahl der Versuche nicht gelingen wird. Die Dateigröße clientseitig vor dem Hochladen zu prüfen, erspart eine Anfrage, die garantiert zu file_too_large führt.

Die API teilt sich ihre Limits mit dem Plan, den Sie bereits auf der Website nutzen – nichts Separates zu konfigurieren.

Sobald ein Minutenlimit gilt, enthält jede Antwort die Header X-RateLimit-Limit und X-RateLimit-Remaining; eine 429-Antwort enthält zusätzlich Retry-After (in Sekunden) — nutzen Sie diese, um rechtzeitig zu drosseln, statt erst auf einen 429 zu reagieren.

Genau dieselbe Konvertierungs-Engine, die auch die Website nutzt – nichts ist nur der API oder nur der Website vorbehalten.

infoVideo und Audio – sowohl Konvertieren als auch Komprimieren – sind derzeit nur über die Website verfügbar: Ein synchroner HTTP-Aufruf eignet sich schlecht für einen Vorgang, der mehrere Minuten dauern kann.