API de TransConvert

De cero a tu primer archivo convertido en tres pasos.

Cada solicitud necesita una clave de API, enviada como token Bearer en la cabecera Authorization.

Disponible en los planes Basic, Lite, Pro y Team. Genera una clave desde tu cuenta →

Prueba tu clave

Una forma rápida de confirmar que una clave funciona antes de escribir código de integración real; por sí sola esto no convertirá nada (no hay archivo adjunto), pero un 400 no_file en lugar de un 401 confirma que la clave en sí es válida.

Un único endpoint gestiona todas las conversiones. Envía una solicitud POST multipart/form-data con tu archivo y los campos que se indican a continuación.

Parámetros

Conversiones habituales

Una referencia rápida para los pares más populares: el mismo endpoint los gestiona todos, solo cambia la combinación de category/target.

Respuesta

En caso de éxito (200): los bytes en bruto del archivo convertido, con las cabeceras Content-Type y Content-Disposition configuradas para él. En caso de error: un cuerpo JSON con la forma {"error": {"code": "...", "message": "..."}} y un código de estado HTTP correspondiente; consulta Errores más abajo.

Reduce el tamaño de un archivo sin cambiar su formato: el mismo formato de entrada y salida. Un par de categorías independiente de la conversión, image-compress y document-compress, cada una con sus propias opciones a continuación.

image-compress

Mismo formato de entrada y salida (JPG/PNG/WEBP/GIF); target_percent indica el tamaño al que debe aproximarse el resultado respecto al original, no un ajuste de calidad fijo.

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 de entrada, PDF de salida, mediante la recompresión propia de Ghostscript: nunca devuelve un archivo más grande que el subido (si la recompresión no ayuda, se recurre al original).

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

Las conversiones de vídeo y audio pueden tardar minutos, demasiado tiempo para mantener abierta una única solicitud síncrona — estas usan un flujo de envío y consulta en lugar del endpoint anterior. Envía un archivo, recibe enseguida un job_id y luego consulta su estado hasta que termine.

Enviar un trabajo

Misma forma de POST multipart que el endpoint principal, en una URL distinta.

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"

Respuesta (202 Accepted)

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

Consultar el estado

Consulta esto cada pocos segundos con el job_id que recibiste. «status» es uno de 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"
}

Webhooks (opcional)

Si indicó un webhook_url al enviar la solicitud, enviaremos ese mismo cuerpo JSON una vez que el trabajo termine, con éxito o error, reintentando varias veces si su endpoint no responde. job-status.php sigue funcionando como respaldo de todos modos.

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

Descargar el resultado

Cuando el estado sea «completed», la respuesta incluye una download_url — la misma URL de estado con &download=1 añadido. Solicitarla transmite entonces los bytes en bruto del archivo convertido, con las mismas cabeceras que cualquier otro endpoint de esta página. El resultado se elimina en el momento en que se descarga, o automáticamente tras un breve período de conservación si nunca se descarga.

scheduleLos resultados de los trabajos se eliminan inmediatamente después de la descarga, o automáticamente tras un breve período de conservación si nunca se descargan — descárgalos cuanto antes.

La misma solicitud en cuatro lenguajes: elige el que mejor encaje con tu stack. Cada uno convierte un photo.jpg local a PNG y guarda el 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());
    }
}

Cada error devuelve un JSON con un "code" sobre el que tu código puede ramificarse, además de un "message" legible por humanos. Algunos errores incluyen campos adicionales (quota_exceeded incluye, por ejemplo, "limit" y "used").

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

Gestión de errores y reintentos

Ramifica tu lógica según el campo JSON "code", no según el texto de "message" (la redacción puede cambiar con el tiempo, el código no). concurrency_limit merece un breve reintento tras unos segundos (se libera en cuanto termina una de tus conversiones en curso); quota_exceeded no se resolverá por sí solo hasta el mes siguiente, así que no lo reintentes en un bucle. conversion_failed es el único código en el que el estado HTTP sigue importando: un 503 es un problema transitorio del servidor que merece un breve reintento, mientras que 400/415/422/500 significan que esa combinación exacta de archivo/destino no tendrá éxito por más veces que la reenvíes. Comprobar el tamaño de un archivo en el cliente antes de subirlo evita desperdiciar una solicitud en un file_too_large garantizado.

La API comparte sus límites con el mismo plan que ya usas en el sitio web; no hay nada independiente que configurar.

Cuando se aplica un límite por minuto, cada respuesta incluye las cabeceras X-RateLimit-Limit y X-RateLimit-Remaining; una respuesta 429 también incluye Retry-After (en segundos) — úselas para reducir la velocidad antes de alcanzar el límite, en lugar de reaccionar solo tras un 429.

El mismo motor de conversión que usa el sitio web; nada es exclusivo de la API ni del sitio web.

infoEl vídeo y el audio (tanto la conversión como la compresión) están disponibles solo en el sitio web por ahora: una llamada HTTP síncrona no encaja bien con una tarea que puede tardar varios minutos.