API di TransConvert

Dal via al tuo primo file convertito in tre passaggi.

Ogni richiesta richiede una chiave API, inviata come Bearer token nell'header Authorization.

Disponibile nei piani Basic, Lite, Pro e Team. Genera una chiave dal tuo account →

Testa la tua chiave

Un modo rapido per verificare che una chiave funzioni prima di scrivere codice di integrazione vero e proprio — da solo questo non converte nulla (nessun file allegato), ma un 400 no_file invece di un 401 conferma che la chiave è valida.

Un unico endpoint gestisce tutte le conversioni. Invia una richiesta POST multipart/form-data con il tuo file e i campi qui sotto.

Parametri

Conversioni comuni

Un riferimento rapido per le combinazioni più diffuse — lo stesso endpoint le gestisce tutte, cambia solo la combinazione di category/target.

Risposta

In caso di successo (200): i byte grezzi del file convertito, con gli header Content-Type e Content-Disposition impostati di conseguenza. In caso di errore: un corpo JSON con la forma {"error": {"code": "...", "message": "..."}} e un codice di stato HTTP corrispondente — vedi Errori qui sotto.

Riduci le dimensioni di un file senza cambiarne il formato — stesso formato in entrata e in uscita. Una coppia di categorie separata dalla conversione, image-compress e document-compress, ciascuna con le proprie opzioni qui sotto.

image-compress

Stesso formato in entrata e in uscita (JPG/PNG/WEBP/GIF) — target_percent indica quanto dovrebbe essere piccolo il risultato rispetto all'originale, non è un'impostazione di qualità fissa.

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 entrata, PDF in uscita, tramite la ricompressione di Ghostscript — non restituisce mai un file più grande di quello caricato (torna all'originale se la ricompressione non ha aiutato).

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

Le conversioni video e audio possono richiedere diversi minuti, troppo a lungo per mantenere aperta una singola richiesta sincrona — per questo usano un flusso di invio e polling invece dell’endpoint qui sopra. Invia un file, ricevi subito un job_id, poi interroga lo stato finché non è completato.

Invia un job

Stessa struttura POST multipart dell’endpoint principale, su un URL diverso.

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"

Risposta (202 Accepted)

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

Interroga lo stato

Interroga questo endpoint ogni pochi secondi con il job_id ricevuto. «status» può essere queued, processing, completed o 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 (facoltativo)

Se hai fornito un webhook_url all'invio, invieremo lo stesso corpo JSON una volta terminato il job — successo o fallimento — riprovando alcune volte se il tuo endpoint non risponde. job-status.php resta comunque disponibile come alternativa.

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

Scarica il risultato

Quando lo stato è «completed», la risposta include un download_url — lo stesso URL di stato con &download=1 aggiunto. Richiamandolo si ottiene lo streaming dei byte grezzi del file convertito, con le stesse intestazioni di ogni altro endpoint di questa pagina. Il risultato viene eliminato nel momento in cui viene scaricato, oppure automaticamente dopo un breve periodo di conservazione se non viene mai scaricato.

scheduleI risultati dei job vengono eliminati immediatamente dopo il download, oppure automaticamente dopo un breve periodo di conservazione se non vengono mai scaricati — scaricali tempestivamente.

La stessa richiesta in quattro linguaggi — scegli quello che corrisponde al tuo stack. Ognuno converte un file locale photo.jpg in PNG e salva il risultato.

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

Ogni errore restituisce un involucro JSON con un "code" su cui il tuo codice può ramificarsi, più un "message" leggibile. Alcuni errori includono campi aggiuntivi (quota_exceeded include ad esempio "limit" e "used").

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

Gestione di errori e ritentativi

Basa la logica sul campo JSON "code", non sul testo di "message" — il testo può cambiare nel tempo, il code no. concurrency_limit vale la pena riprovarlo dopo pochi secondi (si libera non appena una delle tue conversioni in corso termina); quota_exceeded non si risolve da solo fino al mese successivo, quindi non riprovare in un ciclo. conversion_failed è l'unico code in cui lo stato HTTP conta ancora: un 503 è un problema temporaneo lato server che vale un breve ritentativo, mentre 400/415/422/500 indicano che quella precisa combinazione di file/target non avrà successo indipendentemente da quante volte la reinvii. Controllare la dimensione del file lato client prima del caricamento evita di sprecare una richiesta su un file_too_large già certo.

L'API condivide i limiti con lo stesso piano che già usi sul sito — non c'è nulla da configurare separatamente.

Quando si applica un limite al minuto, ogni risposta include le intestazioni X-RateLimit-Limit e X-RateLimit-Remaining; una risposta 429 include anche Retry-After (in secondi) — usateli per rallentare prima di raggiungere il limite, invece di reagire solo dopo un 429.

Esattamente lo stesso motore di conversione usato dal sito — nulla è esclusivo dell'API o del sito.

infoVideo e audio — sia la conversione che la compressione — sono per ora disponibili solo sul sito: una chiamata HTTP sincrona non è adatta a un'elaborazione che può richiedere diversi minuti.