TransConvert API

Do zero ao seu primeiro arquivo convertido em três passos.

Toda requisição precisa de uma chave de API, enviada como Bearer token no cabeçalho Authorization.

Disponível nos planos Basic, Lite, Pro e Equipe. Gere uma chave na sua conta →

Teste sua chave

Uma forma rápida de confirmar que uma chave funciona antes de escrever qualquer código de integração de verdade — isso sozinho não converte nada (nenhum arquivo anexado), mas um 400 no_file em vez de um 401 confirma que a chave em si é válida.

Um único endpoint cuida de todas as conversões. Envie uma requisição POST multipart/form-data com seu arquivo e os campos abaixo.

Parâmetros

Conversões comuns

Uma referência rápida para os pares mais populares — o mesmo endpoint cuida de todos eles, apenas com uma combinação diferente de category/target.

Resposta

Em caso de sucesso (200): os bytes brutos do arquivo convertido, com os cabeçalhos Content-Type e Content-Disposition definidos para ele. Em caso de falha: um corpo JSON no formato {"error": {"code": "...", "message": "..."}} com um código de status HTTP correspondente — veja Erros abaixo.

Reduza um arquivo sem mudar o formato — mesmo formato na entrada e na saída. Um par de categorias separado da conversão, image-compress e document-compress, cada uma com suas próprias opções abaixo.

image-compress

Mesmo formato na entrada e na saída (JPG/PNG/WEBP/GIF) — target_percent é o quão pequeno o resultado deve tentar ficar em relação ao original, não uma configuração fixa de qualidade.

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 entrada, PDF na saída, via a própria recompressão do Ghostscript — nunca retorna um arquivo maior do que o enviado (usa o original como alternativa se a recompressão não ajudar).

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

Conversões de vídeo e áudio podem levar minutos — tempo demais para manter uma única requisição síncrona aberta — então elas usam um fluxo de enviar-e-consultar em vez do endpoint acima. Envie um arquivo, receba um job_id na hora e consulte o status até terminar.

Enviar um job

O mesmo formato de POST multipart do endpoint principal, em uma URL diferente.

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"

Resposta (202 Accepted)

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

Consultar o status

Consulte este endpoint a cada poucos segundos com o job_id que você recebeu. "status" é um destes: queued, processing, completed ou 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 (opcional)

Se você informou um webhook_url ao enviar, enviaremos esse mesmo corpo JSON assim que o job terminar — sucesso ou falha — tentando novamente algumas vezes se seu endpoint não responder. O job-status.php continua funcionando como 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"
}

Baixar o resultado

Quando o status for "completed", a resposta inclui um download_url — a mesma URL de status com &download=1 adicionado. Ao requisitá-la, você recebe os bytes brutos do arquivo convertido, com os mesmos cabeçalhos de qualquer outro endpoint desta página. O resultado é excluído no momento em que é baixado, ou automaticamente após um curto período de retenção caso nunca seja baixado.

scheduleOs resultados dos jobs são excluídos imediatamente após o download, ou automaticamente após um curto período de retenção caso nunca sejam baixados — baixe assim que possível.

A mesma requisição em quatro linguagens — escolha a que combina com sua stack. Cada uma converte um photo.jpg local para PNG e salva o resultado.

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

Toda falha retorna um envelope de erro JSON com um "code" no qual seu código pode se basear, além de uma "message" legível por humanos. Alguns erros incluem campos extras (quota_exceeded inclui "limit" e "used", por exemplo).

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

Lidando com erros e novas tentativas

Baseie sua lógica no campo JSON "code", não no texto de "message" — a redação pode mudar com o tempo, o código não. concurrency_limit vale a pena tentar de novo em poucos segundos (ele se resolve assim que uma das suas conversões em andamento termina); quota_exceeded não se resolve sozinho até o mês seguinte, então não tente de novo em loop. conversion_failed é o único código em que o status HTTP ainda importa: um 503 é um problema passageiro do lado do servidor que vale uma nova tentativa curta, enquanto 400/415/422/500 significam que aquela combinação exata de arquivo/target não vai funcionar não importa quantas vezes você reenvie. Verificar o tamanho de um arquivo no lado do cliente antes de enviar evita gastar uma requisição com um file_too_large garantido.

A API compartilha os limites do mesmo plano que você já usa no site — nada separado para configurar.

Quando um limite por minuto se aplica, cada resposta inclui os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining; uma resposta 429 também inclui Retry-After (em segundos) — use-os para desacelerar antes de atingir o limite, em vez de reagir somente após um 429.

Exatamente o mesmo mecanismo de conversão que o site usa — nada é exclusivo da API ou exclusivo do site.

infoVídeo e áudio — tanto conversão quanto compressão — são exclusivos do site por enquanto: uma chamada HTTP síncrona não é adequada para uma tarefa que pode levar vários minutos.