API de conversion de fichiers

Convertissez des fichiers depuis votre propre code avec les mêmes convertisseurs que le site : une clé d'API, une interface REST simple, des crédits et des webhooks.

Démarrage rapide

Créez une clé sur la page de votre compte, puis envoyez un fichier et le format souhaité :

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 réponse décrit la conversion. Avec wait=30, une conversion rapide est déjà terminée dans la même réponse ; sinon, interrogez son statut plus tard. Téléchargez ensuite le résultat :

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

Authentification

Envoyez votre clé dans l'en-tête Authorization sous la forme "Bearer ". Les clés se créent et se révoquent sur la page de votre compte et ne sont affichées qu'une fois. Gardez-les secrètes : toute personne disposant de votre clé peut dépenser vos crédits.

Points de terminaison

Entrée, options et formats

Envoyez le fichier dans le champ multipart "file", ou un lien public dans "url" (nos serveurs le téléchargent). Le format source est déduit du nom du fichier ; s'il n'en a pas, envoyez "source". Les options comme la qualité peuvent être envoyées comme champs simples (quality=85) ou comme options[quality]=85. GET /v1/formats/{source} liste tous les formats cibles avec leurs options et limites.

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

Attendre le résultat

Les conversions passent par une file d'attente. Interrogez GET /v1/conversions/{id} jusqu'à ce que le statut soit succeeded ou failed, attendez jusqu'à 30 secondes dans la requête elle-même avec wait=30, ou envoyez une callback_url et nous vous appellerons. Un résultat peut être téléchargé plusieurs fois pendant 24 heures.

Crédits et limites

Une conversion coûte les mêmes crédits que sur le site : le poids du type de conversion multiplié par la tranche de taille du fichier, et uniquement en cas de réussite. Les offres payantes consomment leurs crédits mensuels. Un compte gratuit reçoit 100 crédits d'API gratuits chaque mois.

Une réponse 429 contient l'en-tête Retry-After. Les conversions comptent aussi dans la limite de votre offre en conversions par 10 minutes, partagée avec le site.

Comparer les offres

Webhooks

Avec une callback_url (https uniquement), nous envoyons un POST contenant la conversion en JSON quand elle se termine. Vérifiez l'en-tête X-101convert-Signature : il contient t, un horodatage Unix, et v1, le HMAC-SHA256 de "t.body" calculé avec le secret de webhooks de la page de votre compte. Refusez les horodatages anciens pour empêcher les rejeux. Les livraisons échouées sont retentées pendant environ une heure et demie.

// 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));

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key avec une valeur unique de votre choix. Si la requête est répétée, par exemple après un délai dépassé, vous récupérez la conversion d'origine au lieu d'une nouvelle et vous ne payez qu'une fois.

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"

Erreurs

Toutes les erreurs ont la même forme. Décidez selon code, qui ne change jamais ; message est destiné aux personnes et suit l'en-tête Accept-Language.

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

Exemples

# 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