Documentation de l’API REST
API REST Conv2pdf : convertissez, fusionnez, découpez, compressez, protégez et numérotez vos PDF depuis votre application — 20 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émarrer
Démarrage rapide
- Créez un compte (gratuit, lien de connexion par e-mail)
- Depuis votre tableau de bord, créez une clé API (plan Dev gratuit, 300 conversions offertes pour tester, valables 12 mois, sans renouvellement)
- Convertissez un fichier en deux appels : l’envoi, qui répond une fois la conversion terminée avec un
download_url, puis le téléchargement.
curl -X POST https://api.conv2pdf.com/v1/convert/office-to-pdf \
-H "Authorization: Bearer cpdf_live_..." \
-F "file=@rapport.docx"
# {"job_id": "abc123…", "status": "success", "download_url": "/v1/download/abc123…", …}
curl https://api.conv2pdf.com/v1/download/abc123… \
-H "Authorization: Bearer cpdf_live_..." \
-o rapport.pdf
download_url est un chemin relatif à l’hôte : préfixez-le de https://api.conv2pdf.com, pas de la base URL, qui se termine déjà par /v1. Le résultat reste téléchargeable une heure.
Node.js
import { readFile, writeFile } from 'node:fs/promises';
const API = 'https://api.conv2pdf.com';
const headers = { Authorization: 'Bearer cpdf_live_...' };
const form = new FormData();
form.append('file', new Blob([await readFile('./rapport.docx')]), 'rapport.docx');
const res = await fetch(`${API}/v1/convert/office-to-pdf`, { method: 'POST', headers, body: form });
const job = await res.json();
if (!res.ok) throw new Error(job.error);
const pdf = await fetch(API + job.download_url, { headers });
await writeFile('./rapport.pdf', Buffer.from(await pdf.arrayBuffer()));
Python
import requests
API = 'https://api.conv2pdf.com'
headers = {'Authorization': 'Bearer cpdf_live_...'}
with open('rapport.docx', 'rb') as f:
r = requests.post(f'{API}/v1/convert/office-to-pdf', headers=headers, files={'file': f})
job = r.json()
if not r.ok:
raise RuntimeError(job['error'])
pdf = requests.get(API + job['download_url'], headers=headers)
with open('rapport.pdf', 'wb') as out:
out.write(pdf.content)
PHP
Avec le SDK officiel (recommandé) : composer require conv2pdf/php, voir le repo et ses exemples.
use Conv2pdf\Conv2pdf;
$c = new Conv2pdf('cpdf_live_...');
$job = $c->convert('office-to-pdf', 'rapport.docx');
$c->download($job['download_url'], 'rapport.pdf');
Sans dépendance :
$api = 'https://api.conv2pdf.com';
$auth = ['Authorization: Bearer cpdf_live_...'];
$ch = curl_init("$api/v1/convert/office-to-pdf");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => $auth,
CURLOPT_POSTFIELDS => ['file' => new CURLFile('rapport.docx')],
]);
$job = json_decode(curl_exec($ch), true);
$ch = curl_init($api . $job['download_url']);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $auth]);
file_put_contents('rapport.pdf', curl_exec($ch));
Authentification et base URL
https://api.conv2pdf.com/v1
Chaque requête porte l’en-tête HTTP Authorization: Bearer <votre_clé>. Une clé absente, révoquée ou inexistante renvoie 401. Les clés se créent depuis le tableau de bord ; toutes celles d’un compte partagent son quota.
Concepts
Cycle d’un job
- Conversion :
POST /v1/convert/:toolrépond quand la conversion est terminée, avec unjob_idet undownload_url. - Téléchargement :
GET /v1/download/:jobId, pendant une heure. Ensuite l’entrée et la sortie sont supprimées, et le téléchargement renvoie410 file_expired. - Suppression, facultative :
DELETE /v1/job/:jobIdefface le job et son fichier sans attendre l’heure.
GET /v1/job/:jobId lit le statut d’un job à tout moment. Un job n’est accessible qu’à la clé qui l’a créé ; une autre reçoit 403 forbidden.
Limites
| Limite | Valeur | Au-delà |
|---|---|---|
| Taille d’un fichier | 10 Mo sur le plan Dev, 200 Mo sur les plans payants | 413 file_too_large |
| Fichiers par conversion | 1 sur le plan Dev (2 pour merge-pdf), 20 sur les plans payants | 402 plan_limit_files |
| Taille d’une requête | 220 Mo, fichiers et champs confondus | 413 payload_too_large |
| Éléments du multipart | 20 fichiers, 10 champs, 32 parts au total | 413 too_many_parts |
| Débit des conversions | 20 par minute et par clé | 429 rate_limited |
| Débit des autres endpoints | 300 requêtes par minute et par IP | 429 rate_limited |
| Conservation des fichiers | 1 h après la conversion | 410 file_expired |
| Pages, durée, taille du résultat | propres à chaque outil, voir sa fiche | 422 too_many_pages, 504 conversion_timeout… |
Quotas et facturation
Chaque compte a un quota selon son plan (voir tarifs API), partagé par toutes ses clés.
- Plans payants : le quota est mensuel et se réinitialise à chaque échéance anniversaire (et non au 1er du mois). L’horodatage de la prochaine remise à zéro est renvoyé dans
quota_period_end; le compteurusedy repart de zéro. - 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, commeperiod_end: un essai n’est pas facturé). - Dépassement : un léger dépassement est toléré (
soft_cap_limit, +10 %) avant le blocage en429 quota_exceeded. - Alertes : un e-mail vous prévient à 80 % du quota puis à épuisement, sur tous les plans, et 30 jours avant l’expiration des crédits d’essai.
L’état du quota se lit à tout moment, sans rien consommer, avec GET /v1/quota. Chaque conversion authentifiée par clé API renvoie le même objet quota.
Décompté
- une conversion qui aboutit ;
- un fichier refusé après avoir été lu : illisible, scanné, trop de pages, déjà protégé.
Gratuit
- 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… ;
- un refus de débit (
429 rate_limited) ; - une panne de notre côté (
500 conversion_failed,504 conversion_timeout).
Erreurs et reprises
Toute réponse d’erreur porte un champ error : un code stable, sur lequel brancher du code. Les champs supplémentaires disent quoi corriger. Les refus à l’entrée (envoi, 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).
- Retenter après le délai indiqué :
429 rate_limited(champretry_afteren secondes, en-têteRetry-After) et503 server_busy(sous 5 s, en-têteRetry-After). - Ne pas retenter avant l’échéance :
429 quota_exceeded, jusqu’àquota_period_end; sur le plan Dev, comme après402 credits_expired, seul un plan payant (upgrade) rouvre l’accès. - Ne jamais retenter :
410 file_expiredet410 job_deleted, la ressource est partie. - Corriger la requête ou le fichier : les autres
4xx. Un paramètre refusé ne coûte rien. - Pannes :
500 conversion_failedet504 conversion_timeoutsont remboursées au quota.
Chaque code, avec les champs qu’il porte, est décrit dans Codes d’erreur.
Référence
Endpoints
| Endpoint | Rôle |
|---|---|
POST /v1/convert/:tool | Convertir un ou plusieurs fichiers |
GET /v1/download/:jobId | Télécharger le résultat |
GET /v1/job/:jobId | Lire le statut d’un job |
DELETE /v1/job/:jobId | Supprimer un job et son fichier |
GET /v1/quota | Lire le quota de la clé, sans rien consommer |
GET /v1/tools | Lister les outils, leurs formats et leurs bornes |
POST /v1/convert/:tool
Effectue une conversion et répond quand elle est terminée. Fichiers et paramètres partent en multipart/form-data : le fichier dans le champ file, répété pour en envoyer plusieurs. Les valeurs de :tool et les champs de chaque outil sont décrits dans Outils.
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, une heure durant. Il est servi avec Cache-Control: no-store et le type MIME du résultat : application/pdf, image/jpeg pour heic-to-jpg, le format DOCX pour pdf-to-word, application/zip pour pdf-to-image et split-pdf.
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). Le job répond ensuite 410 job_deleted.
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 l’objet quota d’une réponse de conversion, seul. 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_..."
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_..."
Outils
20 outils disponibles. La liste machine à jour (formats acceptés, bornes de fichiers) est renvoyée par GET /v1/tools. Le type d’un fichier se lit à son contenu, pas à son extension (voir 415 unsupported_content).
Les paramètres sont des champs multipart/form-data envoyés avec le fichier. Sur pdf-to-word, pdf-to-image, compress-pdf, split-pdf, extract-pages, rotate-pdf, watermark-pdf et page-numbers-pdf, le champ password ouvre 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.
Outil (:tool) | Entrée | Fichiers | Sortie |
|---|---|---|---|
| Conversions | |||
image-to-pdf | PNG, JPG, WEBP, GIF, TIFF | 1 | |
heic-to-jpg | HEIC, HEIF | 1 | JPG |
heic-to-pdf | HEIC, HEIF | 1 | |
office-to-pdf | DOC(X/M), ODT, RTF, TXT, XLS(X/M), ODS, CSV, PPT(X/M), ODP, ODG, SXW/SXC/SXI/SXD, FODT/FODS/FODP/FODG, PAGES | 1 | |
epub-to-pdf | EPUB | 1 | |
xps-to-pdf | XPS, OXPS | 1 | |
ps-to-pdf | PS, EPS | 1 | |
html-to-pdf | HTML, HTM, XHTML | 1 | |
url-to-pdf | adresse http/https (champ url) | 0 | |
pdf-to-word | 1 | DOCX | |
pdf-to-image | 1 | ZIP (1 image/page) | |
| Opérations PDF | |||
merge-pdf | 2 à 20 | ||
split-pdf | 1 | ZIP (1 PDF/page) | |
extract-pages | 1 | ||
compress-pdf | 1 | ||
rotate-pdf | 1 | ||
protect-pdf | 1 | ||
unlock-pdf | 1 | ||
watermark-pdf | 1 | ||
page-numbers-pdf | 1 | ||
Conversions
image-to-pdf
PNG, JPG, WEBP, GIF, TIFF → PDF · 1 fichier · aucun champ
Erreurs propres : 415 unsupported_format, image dans un format que l’outil ne sait pas lire.
curl -X POST https://api.conv2pdf.com/v1/convert/image-to-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@photo.jpg"
heic-to-jpg
HEIC, HEIF → JPG · 1 fichier · aucun champ
curl -X POST https://api.conv2pdf.com/v1/convert/heic-to-jpg \
-H "Authorization: Bearer cpdf_live_..." -F "file=@IMG_0001.heic"
heic-to-pdf
HEIC, HEIF → PDF · 1 fichier · aucun champ
curl -X POST https://api.conv2pdf.com/v1/convert/heic-to-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@IMG_0001.heic"
office-to-pdf
DOC(X/M), ODT, RTF, TXT, XLS(X/M), ODS, CSV, PPT(X/M), ODP, ODG, SXW/SXC/SXI/SXD, FODT/FODS/FODP/FODG, PAGES → PDF · 1 fichier · aucun champ
Convertit aussi les documents Apple Pages, reconnus à leur extension .pages ; les fichiers Numbers et Keynote sont refusés.
Erreurs propres : 415 unsupported_content avec detected_type iwork_numbers ou iwork_keynote pour un fichier Numbers ou Keynote ; 422 password_protected pour un document iWork verrouillé.
curl -X POST https://api.conv2pdf.com/v1/convert/office-to-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@rapport.docx"
epub-to-pdf
EPUB → PDF · 1 fichier · aucun champ
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.
Erreurs propres : 422 epub_blank_output, pages qui sortiraient blanches (mise en page fixe faite d’images pleine page, comme une bande dessinée ou un album illustré) ; 422 epub_too_long, livre de plus de 1 500 pages (le corps porte pages et max_pages) ; 422 password_protected, livre sous DRM.
curl -X POST https://api.conv2pdf.com/v1/convert/epub-to-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@livre.epub"
xps-to-pdf
XPS, OXPS → PDF · 1 fichier · aucun champ
Documents XPS et OpenXPS, reconnus à leur contenu : chaque page garde sa taille, ses polices et ses tracés vectoriels ; les liens et le plan du document sont conservés.
Erreurs propres : 422 source_unreadable, paquet que le moteur ne peut pas ouvrir ; 422 too_many_pages au-delà de 1 500 pages (le corps porte pages et max_pages).
curl -X POST https://api.conv2pdf.com/v1/convert/xps-to-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@commande.xps"
ps-to-pdf
PS, EPS → PDF · 1 fichier · aucun champ
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.
Erreurs propres : 422 source_unreadable, programme PostScript qui échoue ; 422 ps_blank_output, fichier qui ne dessine aucune page, comme une police ou une bibliothèque de fonctions enregistrée en PostScript ; 422 too_many_pages au-delà de 500 pages ; 504 conversion_timeout au-delà de 30 secondes.
curl -X POST https://api.conv2pdf.com/v1/convert/ps-to-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@dessin.eps"
html-to-pdf
HTML, HTM, XHTML → PDF · 1 fichier · aucun champ
Rend la version imprimable de la page, celle que donnerait un Ctrl+P : le texte reste sélectionnable, les liens cliquables, et les titres deviennent des signets. Le format de page et les marges viennent du @page du document ; à défaut, A4 avec 1 cm de marge. Le JavaScript de la page est exécuté, avec un court délai de stabilisation. La page n’a accès à aucun fichier local ni à aucun réseau privé, et le contenu d’une iframe d’une autre origine n’est pas imprimé (zone vide, sans erreur).
Erreurs propres : 422 html_blank_output, sortie où rien n’est dessiné (fichier vide, corps masqué par la feuille de style), refusée plutôt que livrée en page blanche ; 422 too_many_pages au-delà de 500 pages ; 504 conversion_timeout au-delà de 60 secondes.
curl -X POST https://api.conv2pdf.com/v1/convert/html-to-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@page.html"
url-to-pdf
adresse http/https → PDF · aucun fichier
Seul outil qui ne prend aucun fichier : il ouvre l’adresse du champ url et la rend comme html-to-pdf, en version imprimable, avec les mêmes plafonds (500 pages, 60 secondes). La page est ouverte sans session : tout ce qui demande une connexion est hors de portée.
Champ : url, requis : adresse http ou https, 2 048 caractères au plus.
Sont refusées en 422 invalid_url, sans être décomptées : une adresse portant des identifiants, une adresse de réseau privé ou de loopback, et un nom qui ne désigne qu’un réseau local. Le motif est dans cause : malformed, scheme, credentials, private_address (avec address_kind), local_name ou too_long.
Erreurs propres : 400 no_file_expected, un fichier a été envoyé ; 422 url_unreachable, l’adresse n’a pas répondu ; 422 url_http_error, la page a répondu par une erreur (son statut dans http_status) ; 422 url_blocked, l’adresse désigne un réseau privé ; 422 url_blank_page, site qui rend une page vide hors navigateur.
curl -X POST https://api.conv2pdf.com/v1/convert/url-to-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "url=https://exemple.com/article"
pdf-to-word
PDF → DOCX · 1 fichier
Renvoie un fichier .docx éditable. L’OCR existe pour les comptes Premium, sur le site uniquement, et n’est pas exposé par l’API.
Champ : password, facultatif : mot de passe d’ouverture du PDF.
Erreurs propres : 422 pdf_scanned_needs_ocr, PDF scanné sans couche texte ; 422 pdf_too_many_pages au-delà de 500 pages.
curl -X POST https://api.conv2pdf.com/v1/convert/pdf-to-word \
-H "Authorization: Bearer cpdf_live_..." -F "file=@rapport.pdf"
pdf-to-image
PDF → ZIP, une image par page · 1 fichier
Rend chaque page en image à 150 DPI.
| Champ | Requis | Valeurs | Défaut |
|---|---|---|---|
format | non | png, jpg | png |
password | non | mot de passe d’ouverture du PDF | — |
Erreurs propres : 422 too_many_pages au-delà de 100 pages ; 422 output_too_large si les images dépassent la taille maximale (le corps porte max_bytes et format).
curl -X POST https://api.conv2pdf.com/v1/convert/pdf-to-image \
-H "Authorization: Bearer cpdf_live_..." -F "file=@rapport.pdf" \
-F "format=png"
Opérations PDF
merge-pdf
PDF → PDF · 2 à 20 fichiers, 2 sur le plan Dev · aucun autre champ
Fusionne les fichiers dans l’ordre d’envoi : répétez le champ file. Un PDF protégé par mot de passe se déverrouille d’abord avec unlock-pdf.
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"
split-pdf
PDF → ZIP, un PDF par page · 1 fichier
Rend chaque page dans son fichier (page-001.pdf, page-002.pdf…), réunis dans une archive ZIP. Le résultat ne porte que les pages : ni les pièces jointes, ni les métadonnées du document. Pour garder une sélection de pages dans un seul PDF, c’est extract-pages.
Champ : password, facultatif : mot de passe d’ouverture du PDF.
Erreurs propres : 422 pdf_single_page, le PDF ne compte qu’une page ; 422 too_many_pages au-delà de 200 pages ; 422 output_too_large si l’archive devait dépasser 600 Mo (le corps porte max_bytes).
Compatibilité : 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.
curl -X POST https://api.conv2pdf.com/v1/convert/split-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@rapport.pdf"
extract-pages
PDF → PDF · 1 fichier
Garde les pages demandées dans un seul PDF. Les pages sortent dans l’ordre écrit, chacune une seule fois. 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.
| Champ | Requis | Valeurs | Défaut |
|---|---|---|---|
ranges | oui | ex. : 1-5,7,10-12 ; 11- va jusqu’à la dernière page, -4 part de la première | — |
password | non | mot de passe d’ouverture du PDF | — |
Erreurs propres : 400 field_required sans ranges ; 400 invalid_page_range, sélection que le document ne permet pas, 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.
curl -X POST https://api.conv2pdf.com/v1/convert/extract-pages \
-H "Authorization: Bearer cpdf_live_..." -F "file=@rapport.pdf" \
-F "ranges=1-5,7,10-12"
compress-pdf
PDF → PDF · 1 fichier
| Champ | Requis | Valeurs | Défaut |
|---|---|---|---|
quality | non | low (72 DPI), medium (150 DPI), high (300 DPI) | medium |
password | non | mot de passe d’ouverture du PDF | — |
curl -X POST https://api.conv2pdf.com/v1/convert/compress-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@gros.pdf" \
-F "quality=medium"
rotate-pdf
PDF → PDF · 1 fichier
| Champ | Requis | Valeurs | Défaut |
|---|---|---|---|
rotation | oui | 90, 180, 270, en degrés, sens horaire | — |
password | non | mot de passe d’ouverture du PDF | — |
curl -X POST https://api.conv2pdf.com/v1/convert/rotate-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@scan.pdf" \
-F "rotation=90"
protect-pdf
PDF → PDF · 1 fichier
Chiffrement AES-256. Le PDF généré demandera le mot de passe à l’ouverture et appliquera les restrictions cochées.
| Champ | Requis | Valeurs | Défaut |
|---|---|---|---|
password | oui | mot de passe à poser, 6 à 64 caractères | — |
prevent_print | non | on interdit l’impression | impression permise |
prevent_copy | non | on interdit la copie de texte | copie permise |
Erreurs propres : 400 password_too_short ou password_too_long (le corps porte min ou max) ; 422 pdf_already_protected, PDF déjà chiffré.
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"
unlock-pdf
PDF → PDF · 1 fichier
Retire le mot de passe et les restrictions d’un PDF.
Champ : password, si le PDF en demande un : 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.
Erreurs propres : 422 pdf_not_protected, PDF sans protection.
curl -X POST https://api.conv2pdf.com/v1/convert/unlock-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@protege.pdf" \
-F "password=secret123"
watermark-pdf
PDF → PDF · 1 fichier
| Champ | Requis | Valeurs | Défaut |
|---|---|---|---|
text | oui | texte du filigrane, 50 caractères au plus | — |
password | non | mot de passe d’ouverture du PDF | — |
Erreurs propres : 400 field_required sans text ; 422 unsupported_characters, le texte contient des caractères que les polices embarquées ne savent pas rendre (le corps porte field, le quota n’est pas décompté).
curl -X POST https://api.conv2pdf.com/v1/convert/watermark-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@contrat.pdf" \
-F "text=CONFIDENTIEL"
page-numbers-pdf
PDF → PDF · 1 fichier
| Champ | Requis | Valeurs | Défaut |
|---|---|---|---|
position | non | bottom-center, bottom-left, bottom-right | bottom-center |
format | non | full (« X sur N »), simple (le numéro seul, sans total) | full |
password | non | mot de passe d’ouverture du PDF | — |
curl -X POST https://api.conv2pdf.com/v1/convert/page-numbers-pdf \
-H "Authorization: Bearer cpdf_live_..." -F "file=@rapport.pdf" \
-F "position=bottom-right"
Codes d’erreur
Le format du corps et ce qu’il faut retenter sont dans Erreurs et reprises. Les erreurs communes à tous les outils, par code HTTP :
| Code | Erreur | Cause |
|---|---|---|
| 400 | not_enough_files / too_many_files | Nombre de fichiers hors bornes pour l’outil. Le corps porte min et provided, ou max. |
| 400 | field_required | Champ obligatoire absent ou vide : ranges sur extract-pages, text sur watermark-pdf. Le corps porte field, et example quand la forme attendue n’est pas évidente. Le quota n’est pas décompté. |
| 400 | invalid_rotation / invalid_page_range / invalid_quality / invalid_format | Paramètre hors des valeurs admises. Le corps porte ce qui est accepté (allowed, valid) et, pour une sélection de pages, le motif dans cause, le morceau refusé dans range et le nombre de pages du document dans total_pages. Le quota n’est pas décompté. |
| 400 | bad_request | Corps multipart refusé par le parseur : nom de champ interdit, champ JSON invalide, ou corps coupé en vol (code: "malformed_multipart"). Le corps porte code. |
| 401 | missing_bearer_token / invalid_api_key / account_not_provisioned | Auth manquante, clé invalide ou révoquée, ou clé sans compte API rattaché. |
| 402 | plan_limit_files | Plus de fichiers que le plan n’en autorise par conversion : 1 sur le plan Dev, 20 sur les plans payants. Le corps porte plan et max_allowed — la limite réellement appliquée, plus haute sur un outil qui exige plusieurs fichiers (merge-pdf en accepte 2 même en Dev). |
| 402 | credits_expired | Crédits d’essai du plan Dev passés leur date de validité (12 mois depuis leur octroi), quel que soit le reliquat. Le corps porte expired_at et upgrade. |
| 403 | forbidden | Job appartient à une autre clé |
| 404 | tool_not_found / job_not_found | Outil ou job inexistant |
| 409 | job_not_ready | Le job existe mais n’a pas de sortie : conversion en cours, échouée ou rejetée. Le corps porte status (pending / failed / rejected). |
| 410 | file_expired / job_deleted | Ressource partie définitivement : TTL de 1 h dépassé, ou job supprimé via DELETE /v1/job/:jobId. Inutile de retenter. |
| 413 | file_too_large | Fichier au-delà de la limite du plan : 10 Mo sur le plan Dev, 200 Mo sur les plans payants. Quand un plan supérieur accepterait le fichier, la réponse porte upgrade avec ce plan, son prix mensuel HT et son plafond. |
| 413 | payload_too_large | Requête entière au-delà de 220 Mo, tous fichiers et champs confondus. Le corps porte max_bytes. |
| 413 | too_many_parts | Trop d’éléments dans le multipart : 20 fichiers, 10 champs, 32 parts au total. Le corps porte limit (la borne franchie) et max. |
| 415 | unsupported_media_type | Le Content-Type de la requête n’est pas parsable. Les conversions s’envoient en multipart/form-data ; tout le reste tombe ici — corps brut (application/pdf, application/octet-stream…), application/json, application/x-www-form-urlencoded, en-tête absent, ou multipart/form-data sans boundary. Le refus intervient avant la lecture du corps. La réponse porte le type reçu (received) et la liste des types parsables (accepted). |
| 415 | unsupported_content | Le contenu du fichier ne correspond pas à l’outil. Le type est déterminé au CONTENU, pas à l’extension du nom : un PDF valide est accepté même sans extension, et un fichier renommé en .pdf est refusé. L’extension ne tranche que ce que le contenu ne dit pas : .doc/.xls/.ppt, texte brut et CSV, Pages et Numbers. Les fichiers Numbers et Keynote sont refusés avec detected_type iwork_numbers ou iwork_keynote. La réponse porte file, le type détecté (detected_type) et bytes. |
| 422 | empty_file | Fichier vide (0 octet). Le corps porte file. |
| 422 | password_protected | Fichier protégé par mot de passe d’ouverture (chiffré) sur un outil qui ne sait pas le déchiffrer, y compris un livre EPUB sous DRM ou un document iWork verrouillé ; retirer la protection avant conversion. Le corps porte file. |
| 422 | needs_password / wrong_password | PDF chiffré sur un outil qui sait le traiter : mot de passe absent, ou refusé par le fichier. Envoyer le champ password. Ni job ni quota ne sont consommés. |
| 422 | too_many_pages | Document au-delà du plafond de pages de l’outil (voir sa fiche), rendu dans max_pages. |
| 422 | source_unreadable | Fichier du bon type, mais que le moteur n’arrive pas à ouvrir : corrompu, tronqué, ou structure hors norme. |
| 429 | rate_limited | Débit dépassé : 20 conversions par minute et par clé sur POST /v1/convert/:tool, 300 requêtes par minute et par IP sur les autres endpoints. La réponse porte retry_after (secondes) et l’en-tête Retry-After ; le quota mensuel n’est pas décompté. |
| 429 | quota_exceeded | Quota atteint. Sur les plans payants, le corps porte quota_period_end, date du prochain rechargement : inutile de retenter avant. Sur le plan Dev, quota_period_end ET period_end valent null — les conversions offertes ne se renouvellent pas, et un essai n’est pas facturé — et le corps porte upgrade, le plan qui rouvre l’accès. |
| 500 | conversion_failed | Le moteur a échoué. Le corps porte job_id et status: "failed". Le quota est remboursé : une panne de notre côté ne se facture pas. |
| 500 | internal_error | Panne hors conversion. Aucun détail n’est publié — les 5xx sont masqués côté serveur. |
| 503 | server_busy | File de conversion saturée (nouvel essai recommandé sous 5 s, en-tête Retry-After) |
| 504 | conversion_timeout | Budget de temps du moteur dépassé. Le corps porte timeout_ms, et le job est failed. Le quota est remboursé. |
Les erreurs propres à un outil sont décrites dans sa fiche :
| Code | Erreur | Outil |
|---|---|---|
| 400 | no_file_expected | url-to-pdf |
| 400 | password_too_short / password_too_long | protect-pdf |
| 415 | unsupported_format | image-to-pdf |
| 422 | epub_blank_output / epub_too_long | epub-to-pdf |
| 422 | html_blank_output | html-to-pdf |
| 422 | invalid_url / url_unreachable / url_http_error / url_blocked / url_blank_page | url-to-pdf |
| 422 | output_too_large | pdf-to-image, split-pdf |
| 422 | pdf_already_protected | protect-pdf |
| 422 | pdf_not_protected | unlock-pdf |
| 422 | pdf_scanned_needs_ocr / pdf_too_many_pages | pdf-to-word |
| 422 | pdf_single_page | split-pdf |
| 422 | ps_blank_output | ps-to-pdf |
| 422 | unsupported_characters | watermark-pdf |
Intégrations
SDK, OpenAPI et 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 les 20 outils aux fichiers qui passent dans vos workflows, et convertit une page web à partir de son adresse. 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é. Fusion, suppression des tâches, reprises et usage par l’agent IA : voir le README sur GitHub.
Utiliser Conv2pdf avec Zapier
L’app officielle Conv2pdf pour Zapier ajoute à vos Zaps une action pour chacun des 20 outils. Connectez-la avec votre clé API et associez un fichier issu d’une étape précédente, ou donnez l’adresse d’une page web : 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. Liste des actions et comportement sur GitHub.
Utiliser Conv2pdf avec un assistant IA (MCP)
Le serveur MCP officiel de Conv2pdf met les 20 outils de l’API à la disposition d’un assistant IA, sur les fichiers de votre ordinateur et sur les pages web à partir de leur adresse : 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 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.
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.