API Documentation

API de conversion de pages web#

Les endpoints de pages web effectuent le rendu d'URL en direct dans un vrai navigateur et les convertissent en PDF, en captures d'écran PNG pleine page, ou en Markdown GitHub-Flavored propre. Les endpoints à URL unique s'exécutent de manière synchrone (ou asynchrone en mode lot), tandis que les endpoints de site web parcourent un site entier via l'analyse du sitemap ou un crawl complet en largeur, puis regroupent chaque page dans une seule archive ZIP. Tous les endpoints partagent le même pipeline de navigateur : fermeture des bannières de cookies, défilement pour le lazy-load, gestion des en-têtes collants, et prise en charge des pages protégées par HTTP Basic Auth, cookies injectés ou en-têtes personnalisés.

Conversions prises en charge#

Conversion Endpoint Description
URL vers PDF POST /v1/convert/url-to-pdf Convertit toute URL accessible publiquement en un PDF haute fidélité, avec une sortie continue sur une seule page ou paginée, des tailles de page personnalisées, des en-têtes/pieds de page, et un mode lot asynchrone.
URL vers capture d'écran POST /v1/convert/url-to-screenshot Capture une capture d'écran pleine page de toute URL sous forme de PNG haute fidélité, en redimensionnant le viewport à la hauteur réelle du contenu afin que la page entière tienne dans une seule image.
URL vers Markdown POST /v1/convert/url-to-markdown Convertit une page web en Markdown GitHub-Flavored propre avec un frontmatter YAML, en utilisant l'extraction Readability pour supprimer le code répétitif. Conçu pour les pipelines d'ingestion LLM et RAG.
Site web vers PDF POST /v1/convert/website-to-pdf Parcourt un site web entier via son sitemap ou un crawl complet en largeur, convertit chaque page découverte en PDF, et regroupe les résultats dans une seule archive ZIP.
Site web vers capture d'écran POST /v1/convert/website-to-screenshot Découvre chaque page d'un site web via son sitemap ou un crawl complet et capture un PNG pleine page de chacune, livré sous forme d'une seule archive ZIP.

Conventions communes#

  • Authentification : Chaque endpoint accepte une clé privée dans l'en-tête X-API-Key ; les trois endpoints à URL unique acceptent également des jetons JWT Bearer à clé publique (limités à une seule URL, au mode synchrone et au téléchargement direct), tandis que les endpoints de site web exigent une clé privée. Voir Authentification.
  • Synchrone vs asynchrone : Les endpoints à URL unique s'exécutent en synchrone par défaut et passent en asynchrone (async_mode=true, HTTP 202 avec un batch_id) pour les traitements par lot ; les endpoints de site web sont toujours asynchrones. Interrogez GET /v1/convert/batch/{batch_id} pour obtenir les résultats. Voir Tâches synchrones et asynchrones.
  • Réponses : Les conversions terminées renvoient une URL de téléchargement présignée et un object_key ; les endpoints à URL unique peuvent à la place renvoyer directement les octets bruts de sortie avec direct_download=true.
  • Paramètres de navigateur et de rendu : viewport_width/viewport_height, handle_cookies, enable_scroll, load_media, wait_for_images et handle_sticky_header sont partagés par les cinq endpoints, tout comme les options auth, cookies (max 50) et headers (max 20) pour les pages protégées. Voir Tâches synchrones et asynchrones.
  • Erreurs et restrictions liées au forfait : Tous les endpoints utilisent les mêmes codes de statut : 400 pour une entrée invalide, 401 pour des identifiants incorrects, 402 pour les limites de quota ou de stockage, et 403 pour les fonctionnalités réservées à certains forfaits (asynchrone, webhooks, sortie ZIP, basic auth, capture de site web). Voir Codes d'erreur.

Questions fréquentes#

Quel endpoint utiliser pour une seule page par rapport à un site web entier ?#

Utilisez url-to-pdf, url-to-screenshot ou url-to-markdown pour une seule URL ou une liste explicite d'URL. Utilisez website-to-pdf ou website-to-screenshot lorsque vous voulez que l'API découvre elle-même les pages via l'analyse de sitemap.xml ou un crawl complet en largeur, et renvoie tout sous forme d'un seul ZIP.

Ces endpoints peuvent-ils convertir des pages nécessitant une connexion ?#

Oui, sur les forfaits avec accès basic auth. Les cinq endpoints acceptent un objet auth pour l'authentification HTTP Basic Auth, jusqu'à 50 cookies injectés pour un accès basé sur une session, et jusqu'à 20 headers personnalisés. Ces options sont utiles pour les sites de staging, les pages réservées aux membres et les tableaux de bord.

Comment obtenir le résultat d'une tâche asynchrone ?#

Les tâches asynchrones renvoient immédiatement HTTP 202 avec un batch_id. Interrogez GET /v1/convert/batch/{batch_id} avec votre clé privée pour obtenir les statuts par URL et les URL de téléchargement présignées, fournissez un callback_url pour recevoir un POST webhook à la fin, ou reposez-vous sur l'e-mail de fin envoyé à notification_email (le propriétaire du projet par défaut).

← Conversion Matrix url-to-pdf →