Video Conversion API
Convert video between MP4, MOV, AVI, MKV, and WEBM. Video encodes can take minutes, so this is an async, submit-then-poll endpoint rather than one blocking request — same ffmpeg engine behind TransConvert's website converter.
curl -X POST \ .../api/v1/convert-async.php \ -H "Authorization: Bearer ..." \ -F "category=video" \ -F "target=MP4" \ -F "file=@clip.mov" # { "job_id": "job_...", "status": "queued" }
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
https://transconvert.com/api/v1/convert-async.php
| Field | Description |
|---|---|
Authorization | Required. "Bearer tc_live_...". |
category | Set to "video". |
target | Required. Output format code: "MP4", "MOV", "AVI", "MKV", or "WEBM". |
file | Required. The video file. |
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" \ -o output.mp4
<?php $ch = curl_init('https://transconvert.com/api/v1/convert-async.php'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer tc_live_your_key_here'], CURLOPT_POSTFIELDS => [ 'category' => 'video', 'target' => 'MP4', 'file' => new CURLFile('clip.mov'), ], ]); $response = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status === 200) { file_put_contents('output.mp4', $response); } else { $error = json_decode($response, true); echo $error['error']['message']; }
const form = new FormData(); form.append('category', 'video'); form.append('target', 'MP4'); form.append('file', new Blob([fs.readFileSync('clip.mov')]), 'clip.mov'); const res = await fetch('https://transconvert.com/api/v1/convert-async.php', { method: 'POST', headers: { Authorization: 'Bearer tc_live_your_key_here' }, body: form, }); if (res.ok) { fs.writeFileSync('output.mp4', Buffer.from(await res.arrayBuffer())); } else { const { error } = await res.json(); console.error(error.message); }
import requests with open('clip.mov', 'rb') as f: response = requests.post( 'https://transconvert.com/api/v1/convert-async.php', headers={'Authorization': 'Bearer tc_live_your_key_here'}, data={'category': 'video', 'target': 'MP4'}, files={'file': f}, ) if response.status_code == 200: with open('output.mp4', '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-async.php') File.open('clip.mov') do |file| req = Net::HTTP::Post::Multipart.new url, 'category' => 'video', 'target' => 'MP4', 'file' => UploadIO.new(file, 'application/octet-stream', 'clip.mov') 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('output.mp4', 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", "video") .addFormDataPart("target", "MP4") .addFormDataPart("file", "clip.mov", RequestBody.create(new File("clip.mov"), MediaType.parse("application/octet-stream"))) .build(); Request request = new Request.Builder() .url("https://transconvert.com/api/v1/convert-async.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("output.mp4"), response.body().bytes()); } else { System.err.println(response.body().string()); } }
Interroga lo stato
Interroga questo endpoint ogni pochi secondi con il job_id ricevuto. «status» può essere queued, processing, completed o failed.
https://transconvert.com/api/v1/job-status.php?job_id=job_...
curl -H "Authorization: Bearer tc_live_your_key_here" \ https://transconvert.com/api/v1/job-status.php?job_id=job_...
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.
Errori
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").
| Status & code | When it happens |
|---|---|
401 missing_key | Non è stato inviato alcun header Authorization. |
401 invalid_key | La chiave non esiste, oppure è stata revocata. |
403 account_suspended | L'account proprietario di questa chiave è sospeso. |
403 plan_required | L'account è sul piano Free — l'accesso API richiede Basic, Lite, Pro o Team. |
400 invalid_category | "category" non era "image" né "document". |
400 invalid_target | «target» non è un formato di output supportato per quella categoria. |
400 no_file | Non è stato inviato alcun file, oppure l'upload è fallito — il campo deve chiamarsi "file". |
413 file_too_large | Il file supera la dimensione massima di caricamento del tuo piano. |
429 quota_exceeded | La quota mensile di minuti di conversione del piano è esaurita. Si azzera all'inizio del mese solare successivo. |
429 concurrency_limit | Troppe conversioni già in corso contemporaneamente per questo account (condiviso con il sito) — attendi che una finisca e riprova. |
404 job_not_found | Non esiste alcun job con questo id per questo account (restituito anche per il job_id di un altro account — la sua esistenza non viene mai rivelata). |
410 result_gone | Il job è stato completato, ma il suo risultato è stato nel frattempo eliminato (i risultati vengono eliminati immediatamente dopo il download, oppure automaticamente dopo un breve periodo di conservazione). |
400/415/422/500/503 conversion_failed | Il file stesso non è stato convertibile — "message" spiega il motivo. Il codice di stato varia in base al motivo: 400/415/422 indicano che il file o il target non funzioneranno indipendentemente da quanti tentativi fai; 500/503 indicano un problema lato server, e in particolare il 503 vale la pena riprovarlo dopo poco. |
Supported formats
MP4, MOV, AVI, MKV, WEBM