API de conversión de archivos

Convierta archivos desde su propio código con los mismos conversores que el sitio web: una clave de API, una interfaz REST sencilla, créditos y webhooks.

Inicio rápido

Cree una clave en la página de su cuenta y envíe un archivo y el formato que desea:

curl -X POST https://api.101convert.com/v1/conversions \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@photo.jpg" \
  -F "target=webp" \
  -F "quality=85" \
  -F "wait=30"

La respuesta describe la conversión. Con wait=30 una conversión rápida ya está terminada en la misma respuesta; si no, consulte su estado más tarde. Después descargue el resultado:

{
  "id": "cnv_01j9z3k8q4x7m2n5p6r8s9t0v1",
  "status": "succeeded",
  "source": "jpg",
  "target": "webp",
  "credits": 2,
  "result": {
    "filename": "photo.webp",
    "size": 48213,
    "download_url": "https://api.101convert.com/v1/conversions/cnv_01j9z3k8q4x7m2n5p6r8s9t0v1/download",
    "expires_at": "…"
  }
}

curl -o photo.webp -H "Authorization: Bearer $API_KEY" \
  https://api.101convert.com/v1/conversions/cnv_01j9z3k8q4x7m2n5p6r8s9t0v1/download

Autenticación

Envíe su clave en la cabecera Authorization como "Bearer ". Las claves se crean y se revocan en la página de su cuenta y se muestran una sola vez. Manténgalas en secreto: cualquiera con su clave puede gastar sus créditos.

Endpoints

Entrada, opciones y formatos

Envíe el archivo como campo multipart "file" o un enlace público como "url" (lo descargan nuestros servidores). El formato de origen se toma del nombre del archivo; si no lo tiene, envíe "source". Las opciones como la calidad se pueden enviar como campos simples (quality=85) o como options[quality]=85. GET /v1/formats/{source} muestra todos los formatos de destino con sus opciones y límites.

curl -X POST https://api.101convert.com/v1/conversions \
  -H "Authorization: Bearer $API_KEY" \
  -d "url=https://example.com/report.docx" \
  -d "target=pdf"

curl -H "Authorization: Bearer $API_KEY" https://api.101convert.com/v1/formats/jpg

Esperar el resultado

Las conversiones se procesan en una cola. Consulte GET /v1/conversions/{id} hasta que el estado sea succeeded o failed, espere hasta 30 segundos en la propia solicitud con wait=30, o envíe una callback_url y le avisaremos. Un resultado se puede descargar repetidamente durante 24 horas.

Créditos y límites

Una conversión cuesta los mismos créditos que en el sitio web: el peso del tipo de conversión por la franja de tamaño del archivo, y solo si tiene éxito. Los planes de pago gastan sus créditos mensuales. Una cuenta gratuita recibe 100 créditos gratuitos de API cada mes.

Una respuesta 429 incluye la cabecera Retry-After. Las conversiones también cuentan para el límite de su plan de conversiones por 10 minutos, compartido con el sitio web.

Comparar planes

Webhooks

Con una callback_url (solo https) le enviamos un POST con la conversión en JSON cuando termina. Compruebe la cabecera X-101convert-Signature: contiene t, una hora Unix, y v1, el HMAC-SHA256 de "t.body" hecho con el secreto de webhooks de la página de su cuenta. Rechace las marcas de tiempo antiguas para evitar reenvíos. Las entregas fallidas se reintentan durante aproximadamente hora y media.

// PHP
[$t, $v1] = array_map(fn ($p) => explode('=', $p, 2)[1],
    explode(',', $_SERVER['HTTP_X_101CONVERT_SIGNATURE']));
$body  = file_get_contents('php://input');
$valid = abs(time() - (int) $t) < 300
    && hash_equals(hash_hmac('sha256', "$t.$body", $webhookSecret), $v1);

// Node.js
const [t, v1] = req.headers['x-101convert-signature'].split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', webhookSecret).update(`${t}.${rawBody}`).digest('hex');
const valid = Math.abs(Date.now() / 1000 - t) < 300
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

Reintentos seguros

Envíe una cabecera Idempotency-Key con un valor único propio. Si la solicitud se repite, por ejemplo tras un tiempo de espera agotado, recibirá la conversión original en lugar de una nueva y pagará una sola vez.

curl -X POST https://api.101convert.com/v1/conversions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: invoice-2026-0042" \
  -F "file=@invoice.docx" -F "target=pdf"

Errores

Todos los errores tienen la misma forma. Decida según code, que nunca cambia; message es para personas y sigue la cabecera Accept-Language.

{
  "error": {
    "code": "file_too_large",
    "message": "…",
    "details": { "max_upload_mb": 60 }
  }
}

Ejemplos

# Python
import requests, time

API = "https://api.101convert.com/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

with open("interview.mp3", "rb") as f:
    c = requests.post(f"{API}/conversions", headers=headers,
                      files={"file": f}, data={"target": "docx"}).json()

while c["status"] not in ("succeeded", "failed"):
    time.sleep(5)
    c = requests.get(c["links"]["self"], headers=headers).json()

if c["status"] == "succeeded":
    open("interview.docx", "wb").write(
        requests.get(c["result"]["download_url"], headers=headers).content)

// PHP (Laravel)
$c = Http::withToken($apiKey)
    ->attach('file', fopen('slides.pptx', 'r'), 'slides.pptx')
    ->post('https://api.101convert.com/v1/conversions', ['target' => 'pdf', 'wait' => 30])
    ->json();

if ($c['status'] === 'succeeded') {
    file_put_contents('slides.pdf', Http::withToken($apiKey)->get($c['result']['download_url'])->body());
}

// JavaScript (Node 18+)
const form = new FormData();
form.append('file', new Blob([await fs.promises.readFile('scan.png')]), 'scan.png');
form.append('target', 'pdf');
form.append('callback_url', 'https://example.com/hooks/101convert');

const res = await fetch('https://api.101convert.com/v1/conversions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
  body: form,
});
const conversion = await res.json(); // status "queued"; the webhook follows