TransConvert API

Od zera do pierwszego przekonwertowanego pliku w trzech krokach.

Każde żądanie wymaga klucza API, wysyłanego jako token Bearer w nagłówku Authorization.

Dostępne w planach Basic, Lite, Pro i Team. Wygeneruj klucz na stronie swojego konta →

Przetestuj swój klucz

Szybki sposób, aby potwierdzić, że klucz działa, zanim napiszesz właściwy kod integracji — sam ten test niczego nie przekonwertuje (brak dołączonego pliku), ale odpowiedź 400 no_file zamiast 401 potwierdza, że sam klucz jest poprawny.

Jeden endpoint obsługuje każdą konwersję. Wyślij żądanie POST typu multipart/form-data z plikiem i poniższymi polami.

Parametry

Popularne konwersje

Szybki przegląd popularnych par formatów — ten sam endpoint obsługuje je wszystkie, zmienia się tylko kombinacja category/target.

Odpowiedź

Przy sukcesie (200): surowe bajty przekonwertowanego pliku, z ustawionymi dla niego nagłówkami Content-Type i Content-Disposition. Przy niepowodzeniu: treść JSON w postaci {"error": {"code": "...", "message": "..."}} wraz z odpowiednim kodem statusu HTTP — zobacz Błędy poniżej.

Zmniejsz rozmiar pliku bez zmiany jego formatu — na wejściu i wyjściu ten sam format. To osobna para kategorii względem konwersji: image-compress i document-compress, każda z własnymi opcjami poniżej.

image-compress

Ten sam format na wejściu i wyjściu (JPG/PNG/WEBP/GIF) — target_percent to przybliżony rozmiar wyniku względem oryginału, do którego dążymy, a nie stały poziom jakości.

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 na wejściu, PDF na wyjściu, dzięki rekompresji wbudowanej w Ghostscript — nigdy nie zwraca pliku większego niż przesłany (jeśli rekompresja nie pomogła, zwracany jest oryginał).

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

Konwersje wideo i audio mogą trwać kilka minut — zbyt długo, by utrzymywać jedno synchroniczne żądanie — dlatego zamiast powyższego endpointu korzystają z modelu wyślij-i-odpytuj. Prześlij plik, od razu otrzymaj job_id, a następnie odpytuj o jego status, aż będzie gotowy.

Prześlij zadanie

Taki sam kształt żądania POST typu multipart jak w głównym endpoincie, tylko pod innym adresem 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"

Odpowiedź (202 Accepted)

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

Odpytuj o status

Odpytuj co kilka sekund, używając otrzymanego job_id. „status” przyjmuje jedną z wartości: queued, processing, completed lub 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"
}

Webhooki (opcjonalnie)

Jeśli podano webhook_url podczas przesyłania, po zakończeniu zadania — sukcesem lub niepowodzeniem — wyślemy tam ten sam JSON, ponawiając próbę kilka razy, jeśli Twój endpoint nie odpowiada. job-status.php nadal działa jako zapasowe rozwiązanie.

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

Pobierz wynik

Gdy status to „completed”, odpowiedź zawiera download_url — ten sam adres URL statusu z dopisanym &download=1. Zażądanie go strumieniuje surowe bajty przekonwertowanego pliku, z takimi samymi nagłówkami jak każdy inny endpoint na tej stronie. Wynik jest usuwany w momencie pobrania, a jeśli nigdy nie zostanie pobrany — automatycznie po krótkim okresie przechowywania.

scheduleWyniki zadań są usuwane natychmiast po pobraniu, a jeśli nigdy nie zostaną pobrane — automatycznie po krótkim okresie przechowywania — pobierz je bez zwłoki.

To samo żądanie w czterech językach — wybierz ten, który pasuje do Twojego stosu technologicznego. Każdy przykład konwertuje lokalny plik photo.jpg do PNG i zapisuje wynik.

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

Każde niepowodzenie zwraca kopertę błędu JSON z polem „code”, po którym Twój kod może rozgałęziać logikę, oraz czytelnym dla człowieka polem „message”. Niektóre błędy zawierają dodatkowe pola (na przykład quota_exceeded zawiera „limit” i „used”).

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

Obsługa błędów i ponawianie prób

Rozgałęziaj logikę na podstawie pola JSON „code”, a nie tekstu „message” — treść komunikatu może się zmieniać, kod nie. concurrency_limit warto krótko ponowić po kilku sekundach (znika, gdy tylko zakończy się jedna z Twoich trwających konwersji); quota_exceeded nie rozwiąże się samo aż do następnego miesiąca, więc nie ponawiaj go w pętli. conversion_failed to jedyny kod, przy którym nadal liczy się status HTTP: 503 to przejściowy problem po stronie serwera, warty jednej krótkiej ponownej próby, natomiast 400/415/422/500 oznaczają, że ta konkretna kombinacja pliku i formatu docelowego nie powiedzie się niezależnie od liczby ponownych prób. Sprawdzenie rozmiaru pliku po stronie klienta przed przesłaniem pozwala uniknąć marnowania żądania na gwarantowany file_too_large.

API współdzieli limity z tym samym planem, którego już używasz na stronie — nie ma nic osobnego do skonfigurowania.

Gdy obowiązuje limit na minutę, każda odpowiedź zawiera nagłówki X-RateLimit-Limit i X-RateLimit-Remaining; odpowiedź 429 zawiera również Retry-After (w sekundach) — użyj ich, aby zwolnić tempo, zanim osiągniesz limit, zamiast reagować dopiero po 429.

Dokładnie ten sam silnik konwersji, którego używa strona — nic nie jest zarezerwowane wyłącznie dla API ani wyłącznie dla strony.

infoWideo i audio — zarówno konwersja, jak i kompresja — są na razie dostępne tylko na stronie: synchroniczne żądanie HTTP słabo pasuje do zadania, które może trwać kilka minut.