Documentation de l’API REST

API REST conv2pdf : convertissez, fusionnez, découpez, compressez, protégez et numérotez vos PDF depuis votre application — 17 outils exposés via 6 endpoints REST. Hébergement dans l’UE (France), RGPD respecté. Aucun service américain n’intervient dans le processus.

Démarrage rapide

1. Créez un compte (gratuit, magic link par email)
2. Depuis votre tableau de bord, créez une clé API (plan Dev gratuit, 300 conversions offertes pour tester, valables 12 mois, sans renouvellement)
3. Authentifiez vos appels avec l’en-tête Authorization: Bearer cpdf_live_…

Base URL

https://api.conv2pdf.com/v1

SDK, OpenAPI & Postman

• SDK PHP officiel : composer require conv2pdf/php (repo et exemples).
• Spécification OpenAPI 3.0 (JSON) — pour générer un client dans un autre langage, l'importer dans un outil (Swagger, Insomnia…) ou alimenter un agent.
• Collection Postman — importez-la, renseignez votre clé, convertissez un PDF en une minute.

Utiliser conv2pdf avec n8n

Le nœud officiel conv2pdf pour n8n applique 14 des 17 outils, tous sauf epub-to-pdf, ps-to-pdf et split-pdf, aux fichiers qui passent dans vos workflows. Sur un n8n auto-hébergé, ouvrez Settings > Community Nodes, choisissez Install et saisissez n8n-nodes-conv2pdf, puis créez un identifiant Conv2pdf API avec votre clé.

Le nœud lit le fichier dans un champ binaire de chaque élément et rend le fichier converti de la même façon. Il fusionne les fichiers de plusieurs éléments, ou de plusieurs champs d’un même élément, supprime la tâche chez conv2pdf une fois le résultat téléchargé, et patiente puis réessaie quand l’API demande de ralentir. L’agent IA de n8n peut l’utiliser comme outil pour lire le quota de la clé. Code source, notes d’utilisation et historique des versions sur GitHub.

Utiliser conv2pdf avec Zapier

L’app officielle conv2pdf pour Zapier ajoute à vos Zaps une action pour 15 des 17 outils, tous sauf ps-to-pdf et split-pdf : documents bureautiques (Apple Pages compris), images, photos HEIC et livres EPUB vers PDF, HEIC vers JPG, et, pour les PDF, fusion, extraction de pages, rotation, numérotation, filigrane, compression, protection par mot de passe, déverrouillage et conversion en Word ou en images. Connectez-la avec votre clé API et associez un fichier issu d’une étape précédente : l’action renvoie le fichier converti et le quota de la clé. Zapier accorde 30 secondes à une étape : les très gros fichiers passent mieux par l’API directement. Les assistants IA comme Claude, ChatGPT ou Cursor peuvent aussi appeler ces actions via Zapier MCP. Le code source est sur GitHub.

Utiliser conv2pdf avec un assistant IA (MCP)

Le serveur MCP officiel de conv2pdf met 15 des 17 outils de l’API, tous sauf ps-to-pdf et split-pdf, à la disposition d’un assistant IA, sur les fichiers de votre ordinateur : Claude Code, Claude Desktop, Cursor et tout client du Model Context Protocol qui lance un serveur local. L’assistant donne le chemin d’un fichier ; le serveur l’envoie à conv2pdf, écrit le résultat à côté de l’original sans jamais écraser un fichier existant, puis supprime la tâche chez conv2pdf. Il lui faut Node.js 22 ou plus récent, et votre clé API dans la variable d’environnement CONV2PDF_API_KEY.

Dans Claude Code :

claude mcp add --env CONV2PDF_API_KEY=cpdf_live_... --transport stdio conv2pdf -- npx -y conv2pdf-mcp

Sous Windows, placez cmd /c devant npx. Dans Claude Desktop, Cursor et les autres clients configurés par un fichier JSON :

{
  "mcpServers": {
    "conv2pdf": {
      "command": "npx",
      "args": ["-y", "conv2pdf-mcp"],
      "env": { "CONV2PDF_API_KEY": "cpdf_live_..." }
    }
  }
}

Dans Claude Code, le plugin conv2pdf installe le même serveur avec un « skill » qui indique à l’assistant quel outil appeler, dans quel ordre, et ce que coûte un appel :

/plugin marketplace add jamalofski/conv2pdf-mcp
/plugin install conv2pdf@conv2pdf

Demandez ensuite ce qu’il vous faut : « convertis rapport.docx en PDF », « fusionne ces trois PDF », « compresse scan.pdf et protège-le par un mot de passe ». Le serveur expose 13 outils : convert_to_pdf pour les documents bureautiques, les images, les photos HEIC et les livres EPUB, un outil par opération sur les PDF, et get_quota pour lire le quota de la clé. Chaque conversion compte dans le quota comme un appel à l’API. Les applications web de Claude et de ChatGPT, qui ne lancent pas de serveur local, passent par Zapier MCP. Code source et notes d’utilisation sur GitHub.

Authentification

Chaque requête doit inclure l’en-tête HTTP Authorization: Bearer <votre_clé>. Une clé révoquée ou inexistante renvoie un code 401. Un quota dépassé renvoie 429 avec les détails de réinitialisation.

Endpoints

GET /v1/tools

Renvoie la liste des outils disponibles, leurs limites et formats acceptés.

curl https://api.conv2pdf.com/v1/tools \
  -H "Authorization: Bearer cpdf_live_..."

POST /v1/convert/:tool

Effectue une conversion. Les fichiers sont envoyés en multipart/form-data.

17 outils disponibles. La liste machine à jour (formats acceptés, bornes de fichiers) est renvoyée par GET /v1/tools.

Paramètres optionnels (champs form-data) :

• extract-pages : ranges requis (ex : 1-5,7,10-12). Les pages sortent dans l’ordre écrit, chacune une seule fois ; 11- va jusqu’à la dernière page, -4 part de la première
• compress-pdf : quality (low, medium par défaut, high)
• protect-pdf : password requis (6 à 64 caractères) ; optionnels prevent_print=on, prevent_copy=on
• unlock-pdf : password, mot de passe actuel du PDF, à retirer ; à omettre pour un PDF qui s’ouvre sans mot de passe mais restreint l’impression ou la copie
• rotate-pdf : rotation requis (90, 180 ou 270)
• watermark-pdf : text requis (texte du filigrane)
• pdf-to-image : format (png par défaut ou jpg)
• page-numbers-pdf : position (bottom-center par défaut, bottom-left, bottom-right) ; format=simple pour le numéro seul (sans total)
• pdf-to-word, pdf-to-image, compress-pdf, split-pdf, extract-pages, rotate-pdf, watermark-pdf, page-numbers-pdf : password, pour ouvrir un PDF qui demande un mot de passe. Le résultat n’en a plus. Un PDF qui ne restreint que l’impression ou la copie n’en demande pas.

extract-pages garde les pages demandées dans un seul PDF ; split-pdf, qui ne prend aucun champ, rend chaque page dans son fichier (page-001.pdf, page-002.pdf…), réunis dans une archive ZIP. Dans les deux cas le résultat ne porte que ces pages : ni les pages écartées, ni les pièces jointes, ni les métadonnées du document. Une sélection que le document ne permet pas renvoie 400 invalid_page_range, avec le motif dans cause (syntax, page_zero, beyond_last_page ou whole_document), le morceau refusé dans range et, une fois le PDF ouvert, son nombre de pages dans total_pages. split-pdf renvoie 422 pdf_single_page sur un PDF d’une seule page, 422 too_many_pages au-delà de 200 pages et 422 output_too_large si l’archive devait dépasser 600 Mo.

Jusqu’en octobre 2026, l’extraction s’appelait split-pdf. Un appel split-pdf qui porte un champ ranges est toujours servi comme extract-pages : une intégration existante n’a rien à changer. Un seul écart : les pages sortent désormais dans l’ordre écrit (5,1,3 rend les pages 5, 1 et 3), et non plus triées.

epub-to-pdf met le livre en page sur du A4, avec son sommaire et ses liens internes ; les polices du livre sont remplacées par des polices standard. Un livre dont les pages sortiraient blanches (mise en page fixe faite d’images pleine page) renvoie 422 epub_blank_output, un livre de plus de 1 500 pages 422 epub_too_long, un livre sous DRM 422 password_protected. office-to-pdf convertit les documents Apple Pages, reconnus à leur extension .pages ; les fichiers Numbers et Keynote sont refusés (415 unsupported_content, avec detected_type iwork_numbers ou iwork_keynote).

ps-to-pdf convertit les fichiers PostScript et EPS, reconnus à leur contenu : le texte reste du texte, les tracés restent vectoriels, un EPS donne une page à la taille du dessin, et un document qui ne déclare aucun format de page est mis en A4. Un programme PostScript qui échoue renvoie 422 source_unreadable, un fichier qui ne dessine aucune page 422 ps_blank_output, un document de plus de 500 pages 422 too_many_pages, une conversion de plus de 30 secondes 504 conversion_timeout.

Exemple : Image → PDF (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/image-to-pdf \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@photo.jpg"

Exemple : Fusion PDF (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/merge-pdf \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@doc1.pdf" \
  -F "file=@doc2.pdf" \
  -F "file=@doc3.pdf"

Exemple : Compression (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/compress-pdf \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@gros.pdf" \
  -F "quality=medium"

Exemple : PDF → Word (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/pdf-to-word \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@rapport.pdf"

Renvoie un fichier .docx éditable. Un PDF scanné (sans couche texte) renvoie 422 pdf_scanned_needs_ocr : l'OCR existe pour les comptes Premium, sur le site uniquement, et n'est pas exposé par l'API ; au-delà de 500 pages, 422 pdf_too_many_pages.

Exemple : PDF → Image (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/pdf-to-image \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@rapport.pdf" \
  -F "format=png"

Rend chaque page en image à 150 DPI et renvoie une archive .zip (une image par page). Champ format : png (défaut) ou jpg. Au-delà de 100 pages, 422 too_many_pages ; si le résultat dépasse la taille maximale, 422 output_too_large.

Exemple : Protection par mot de passe (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/protect-pdf \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@confidentiel.pdf" \
  -F "password=secret123" \
  -F "prevent_print=on" \
  -F "prevent_copy=on"

Chiffrement AES-256. Le PDF généré demandera le mot de passe à l’ouverture et appliquera les restrictions cochées.

Réponse en cas de succès

L’objet quota n’est présent que pour les appels authentifiés par clé API.

{
  "job_id": "abc123…",
  "status": "success",
  "download_url": "/v1/download/abc123…",
  "size_bytes": 124533,
  "quota": {
    "plan": "starter",
    "quota": 1000,
    "used": 42,
    "soft_cap_limit": 1100,
    "status": "ok",
    "period_end": 1715789012345,
    "quota_period_end": 1715789012345,
    "credits_expire_at": null
  }
}

GET /v1/download/:jobId

Télécharge le fichier converti. Le fichier est servi avec son type MIME (application/pdf, le format DOCX pour PDF → Word, ou application/zip pour PDF → Image) et Cache-Control: no-store. Disponible une heure après la conversion.

curl https://api.conv2pdf.com/v1/download/abc123… \
  -H "Authorization: Bearer cpdf_live_..." \
  -o sortie.pdf

GET /v1/job/:jobId

Renvoie le statut et les métadonnées d’un job (status, taille, dates). Pratique pour vérifier qu’une conversion est prête avant de la télécharger.

curl https://api.conv2pdf.com/v1/job/abc123… \
  -H "Authorization: Bearer cpdf_live_..."

DELETE /v1/job/:jobId

Supprime immédiatement un job et son fichier, sans attendre l’expiration automatique (1 h).

curl -X DELETE https://api.conv2pdf.com/v1/job/abc123… \
  -H "Authorization: Bearer cpdf_live_..."

GET /v1/quota

Renvoie l’état du quota de la clé : plan, consommé, plafonds et échéances, soit le même objet quota que celui d’une conversion. L’appel est gratuit et sans effet, c’est donc celui qui valide une clé, par exemple dans le test d’identifiants d’un connecteur. Il répond aussi quand le quota est au plafond (status vaut hard_cap) ou que l’essai Dev a expiré (credits_expire_at est passé), là où les conversions répondent 429 ou 402.

curl https://api.conv2pdf.com/v1/quota \
  -H "Authorization: Bearer cpdf_live_..."

{
  "plan": "starter",
  "quota": 1000,
  "used": 42,
  "soft_cap_limit": 1100,
  "status": "ok",
  "period_end": 1715789012345,
  "quota_period_end": 1715789012345,
  "credits_expire_at": null
}

Exemples : Node.js

import { readFile } from 'node:fs/promises';

const file = await readFile('./photo.jpg');
const formData = new FormData();
formData.append('file', new Blob([file]), 'photo.jpg');

const res = await fetch('https://api.conv2pdf.com/v1/convert/image-to-pdf', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer cpdf_live_...' },
  body: formData
});
const data = await res.json();
console.log(data.download_url);

Exemples : Python

import requests

with open('photo.jpg', 'rb') as f:
    r = requests.post(
        'https://api.conv2pdf.com/v1/convert/image-to-pdf',
        headers={'Authorization': 'Bearer cpdf_live_...'},
        files={'file': f}
    )
print(r.json()['download_url'])

Exemples : PHP

SDK officiel (recommandé)

Installez le SDK : composer require conv2pdf/php. Voir le repo et ses exemples.

use Conv2pdf\Conv2pdf;

$c = new Conv2pdf('cpdf_live_...');
$job = $c->convert('image-to-pdf', 'photo.jpg');
$c->download($job['download_url'], 'photo.pdf');

Sans dépendance (requête brute)

$ch = curl_init('https://api.conv2pdf.com/v1/convert/image-to-pdf');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer cpdf_live_...'],
  CURLOPT_POSTFIELDS => ['file' => new CURLFile('photo.jpg')],
]);
$data = json_decode(curl_exec($ch), true);
echo $data['download_url'];

Codes d’erreur

Toute réponse d’erreur porte un champ error : un code stable, sur lequel brancher du code. Les champs supplémentaires listés ci-dessous disent quoi corriger. Les refus à l’entrée (upload, plan, contenu) portent aussi plan ; les erreurs survenues pendant la conversion portent job_id et status (rejected pour un verdict sur le fichier, failed pour une panne).

Quotas et réinitialisation

Chaque compte a un quota selon son plan (voir tarifs API), partagé par toutes ses clés. Sur les plans payants, le quota est mensuel et se réinitialise à chaque échéance anniversaire (et non au 1^er du mois) : le timestamp de la prochaine remise à zéro est renvoyé dans quota_period_end, et le compteur used repart de zéro. Sur le plan Dev, les 300 conversions offertes à l’inscription sont valables 12 mois depuis leur octroi (credits_expire_at) et ne se renouvellent pas (quota_period_end à null, comme period_end : un essai n’est pas facturé). Un email vous prévient à 80 % du quota puis à épuisement, sur tous les plans, et 30 jours avant l’expiration des crédits d’essai. Un léger dépassement est toléré (soft_cap_limit, +10 %) avant le blocage en 429. L’état du quota se lit à tout moment, sans rien consommer, avec GET /v1/quota.

Une conversion est décomptée quand elle aboutit, et quand le fichier est refusé après avoir été lu : illisible, scanné, trop de pages, déjà protégé. Ne coûtent rien : un fichier refusé à l’arrivée (type, taille, mot de passe manquant), un paramètre refusé (plage de pages, rotation, qualité, mot de passe trop court…) et une panne de notre côté.

Confidentialité

Les fichiers (entrée et sortie) sont supprimés au bout d’une heure. Une seule exception tient au service lui-même : si une conversion échoue, le fichier envoyé est gardé 72 heures, le temps d’en trouver la cause, puis supprimé. Une seule chose peut prolonger la vie d’un fichier converti, et elle passe par le site : depuis le tableau de bord, le titulaire du compte peut créer un lien de partage pour un job — y compris produit par l’API — auquel cas la copie partagée vit jusqu’à l’échéance du lien (sept jours au plus en Gratuit, trente en Premium) ou jusqu’à sa révocation. Aucun résultat n’est mis en cache. L’intégralité du traitement a lieu sur des serveurs OVHcloud, en France. Voir notre politique de confidentialité pour le détail.

Support

Pour toute question technique, utilisez notre formulaire de contact (sujet « Question technique »). Plans Business et Sur-mesure : support prioritaire avec SLA contractuel.