API Documentation

Formats pris en charge#

Toutes les extensions que l'API accepte et tous les formats qu'elle restitue, un tableau par famille de convertisseurs. Les listes présentées ici sont celles que le code vérifie : une extension absente est donc réellement rejetée, et pas seulement non documentée.

Si c'est plutôt l'appariement qui vous intéresse (telle entrée, telle sortie, et le chemin d'endpoint qui les relie), la matrice de conversion réunit les 51 endpoints dans un seul tableau parcourable.

Pages web#

Cinq endpoints qui prennent une URL dans un corps JSON plutôt qu'un fichier envoyé.

Endpoint Entrée Sortie
POST /v1/convert/url-to-pdf Une URL, ou un tableau d'URL PDF (application/pdf)
POST /v1/convert/url-to-screenshot Une URL, ou un tableau d'URL PNG (image/png)
POST /v1/convert/url-to-markdown Une URL, ou un tableau d'URL Markdown (text/markdown; charset=utf-8)
POST /v1/convert/website-to-pdf Une URL de site, crawlée ou lue depuis sitemap.xml ZIP de PDF
POST /v1/convert/website-to-screenshot Une URL de site, crawlée ou lue depuis sitemap.xml ZIP de PNG

Les captures d'écran sont en PNG. Il n'existe pas d'option de capture en JPEG ou en WebP : l'appel de capture est codé en dur sur PNG. Les deux endpoints website-to-* sont async uniquement et répondent toujours 202 avec un batch_id et un output_format valant zip.

Documents vers PDF#

Onze endpoints à cible unique, chacun étant un envoi multipart/form-data avec le document dans le champ file. La sortie est toujours un PDF unique. Le fourre-tout anything-to-pdf est le douzième et dispose de sa propre section ci-dessous.

Endpoint Entrée acceptée Moteur
POST /v1/convert/html-to-pdf .html, .htm WeasyPrint
POST /v1/convert/markdown-to-pdf .md, .markdown WeasyPrint
POST /v1/convert/doc-to-pdf .doc, .docx LibreOffice
POST /v1/convert/excel-to-pdf .xls, .xlsx LibreOffice
POST /v1/convert/ppt-to-pdf .ppt, .pptx LibreOffice
POST /v1/convert/odt-to-pdf .odt LibreOffice
POST /v1/convert/ods-to-pdf .ods LibreOffice
POST /v1/convert/odp-to-pdf .odp LibreOffice
POST /v1/convert/ots-to-pdf .ots LibreOffice
POST /v1/convert/pages-to-pdf .pages LibreOffice
POST /v1/convert/numbers-to-pdf .numbers LibreOffice

C'est le moteur qui détermine quelles pdf_options sont admises. Le HTML et le Markdown passent par WeasyPrint et acceptent la taille de page, l'orientation, les marges, l'échelle, l'en-tête et le pied de page. Les neuf endpoints adossés à LibreOffice reprennent la géométrie de page du document source : ils n'honorent donc que grayscale et renvoient 400 lorsqu'une option de géométrie est définie explicitement.

anything-to-pdf#

POST /v1/convert/anything-to-pdf accepte 36 extensions et renvoie toujours un PDF. Il fonctionne uniquement par envoi de fichier : il ne prend aucune URL.

.bmp   .csv   .doc   .docx  .epub  .gif
.heic  .heif  .htm   .html  .jpeg  .jpg
.markdown     .md    .mdown .mkd   .numbers
.odp   .ods   .odt   .ots   .pages .pdf
.png   .ppt   .pptx  .rtf   .svg   .text
.tif   .tiff  .txt   .webp  .xhtml .xls
.xlsx

C'est l'extension qui choisit le moteur :

Groupe d'entrée Extensions Moteur
Office, OpenDocument, iWork, RTF, CSV .doc .docx .xls .xlsx .ppt .pptx .odt .ods .odp .ots .pages .numbers .rtf .csv LibreOffice headless
HTML .html .htm .xhtml WeasyPrint
Markdown .md .markdown .mdown .mkd WeasyPrint
Texte brut .txt .text Encadré dans un bloc à chasse fixe, puis WeasyPrint
EPUB .epub EPUB vers Markdown, puis WeasyPrint
Images matricielles .png .jpg .jpeg .gif .bmp .tiff .tif .webp .heic .heif Pillow
SVG .svg CairoSVG
PDF .pdf Transmis tel quel après validation

Deux conséquences de ce routage méritent d'être connues avant d'envoyer un fichier :

  • La géométrie de page (page_size, page_width, page_height, orientation, marges, scale, header, footer) n'est honorée que pour les entrées HTML, Markdown, texte brut, EPUB, image et SVG. Définissez-en une explicitement sur une entrée bureautique ou PDF et la requête renvoie 400. grayscale fonctionne pour toutes les entrées.
  • Un PDF envoyé est accepté et transmis tel quel, après vérification que les octets commencent par %PDF-. Combiné à grayscale, cela fait de cet endpoint le moyen de passer un PDF existant en niveaux de gris.

anything-to-markdown#

POST /v1/convert/anything-to-markdown accepte 22 extensions et renvoie toujours un seul fichier .md en UTF-8.

.csv   .doc   .docx  .epub  .htm   .html
.markdown     .md    .mdown .mkd   .odp
.ods   .odt   .pdf   .ppt   .pptx  .rtf
.text  .txt   .xhtml .xls   .xlsx

Regroupées selon la façon dont chacune est lue :

Groupe d'entrée Extensions Chemin
Texte et Markdown .txt .text .md .markdown .mdown .mkd Lu directement
HTML .html .htm .xhtml HTML vers Markdown
Formats hérités et OpenDocument .doc .ppt .xls .odt .ods .odp .rtf LibreOffice vers HTML, puis vers Markdown
Extracteurs natifs .pdf .docx .pptx .xlsx .csv .epub Extracteur propre au format

Trois points à anticiper :

  • Les images sont rejetées. .png, .jpg, .jpeg, .gif, .bmp, .webp, .tiff et .tif renvoient 400 avec Image OCR ('<ext>') is not yet supported on this endpoint. Il n'y a pas d'OCR sur cet endpoint : une page scannée dans un fichier image n'a donc aujourd'hui aucun chemin vers du texte.
  • .ots, .pages et .numbers ne sont pas acceptés ici, alors même qu'anything-to-pdf prend les trois. Faites-les d'abord passer par anything-to-pdf, puisque .pdf figure dans la liste ci-dessus.
  • La sortie est normalisée avant d'être renvoyée : les CRLF deviennent des LF, les suites de trois lignes vides ou plus sont réduites, et le fichier se termine par un saut de ligne.

L'extraction s'exécute sous des plafonds de ressources qui protègent contre les envois hostiles. Les entrées à base de ZIP (EPUB, DOCX, XLSX, PPTX) sont rejetées au-delà de 400 MB déclarés décompressés ou de 10,000 entrées. Les tableaux produits tronquent les cellules à 500 caractères et s'arrêtent à 5,000 lignes de corps. L'extracteur PDF plafonne à 2,000 pages et 20,000 mots par page.

Formats de données#

Onze endpoints, tous des envois synchrones. L'extension du fichier doit correspondre à l'endpoint auquel vous l'envoyez.

Endpoint Entrée acceptée Sortie
POST /v1/convert/json-to-xml .json .xml
POST /v1/convert/xml-to-json .xml .json
POST /v1/convert/json-to-yaml .json .yaml
POST /v1/convert/yaml-to-json .yaml, .yml .json
POST /v1/convert/json-to-csv .json .csv
POST /v1/convert/csv-to-json .csv .json
POST /v1/convert/json-to-toml .json .toml
POST /v1/convert/toml-to-json .toml .json
POST /v1/convert/csv-to-xml .csv .xml
POST /v1/convert/xml-to-csv .xml .csv
POST /v1/convert/markdown-to-html .md, .markdown .html

Images#

Vingt-deux endpoints : vingt conversions entre JPEG, PNG, SVG, HEIC et WebP (chaque paire ordonnée), plus pdf-to-jpeg et compress-image. Lisez ce tableau comme « en quoi puis-je transformer ceci ».

Entrée Sorties disponibles
JPEG (.jpeg, .jpg) PNG, SVG, HEIC, WebP
PNG (.png) JPEG, SVG, HEIC, WebP
SVG (.svg) JPEG, PNG, HEIC, WebP
HEIC (.heic, .heif) JPEG, PNG, SVG, WebP
WebP (.webp) JPEG, PNG, SVG, HEIC
PDF (.pdf) JPEG, via pdf-to-jpeg
PNG, JPEG, WebP Le même format, en plus léger, via compress-image

Les noms d'endpoints suivent la paire : jpeg-to-png, svg-to-webp, heic-to-jpeg, et ainsi de suite. Notez que les endpoints JPEG s'écrivent jpeg-, pas jpg-, même si les fichiers .jpeg comme .jpg sont acceptés.

compress-image conserve le format d'entrée : PNG en entrée, PNG en sortie. Son paramètre facultatif target_size_kb doit valoir au moins 1, et une valeur inférieure renvoie 400 avant qu'aucune op ne soit dépensée.

pdf-to-jpeg renvoie un JPEG brut pour un PDF d'une seule page, et un ZIP allant de page_1.jpeg à page_N.jpeg pour un PDF multipage. Toute sortie de convertisseur qui commence par une signature ZIP est livrée avec l'extension .zip, ce qui explique qu'un même endpoint puisse vous restituer deux types de contenu différents.

Plafonds de pixels#

Ils sont vérifiés indépendamment de la limite de taille de fichier de votre plan, car un petit fichier peut se décoder en un bitmap énorme.

Limite Valeur S'applique à
Pixels décodés 40,000,000 Chaque endpoint d'image, vérifié juste après l'ouverture de l'image
Dimension de sortie SVG 10,000 px par côté Rastérisation SVG (svg-to-*)
Pixels de sortie SVG 25,000,000 au total Rastérisation SVG (svg-to-*)
Taille de rendu 25,000,000 px par page pdf-to-jpeg, qui réduit le rendu pour tenir dans la limite
Nombre de pages 500 pages pdf-to-jpeg

Les requêtes SVG qui dépassent un plafond de dimension renvoient 400 avant qu'aucune op ne soit comptée. Ne passer que width ou que height fait déduire l'autre du ratio intrinsèque du SVG ; lorsque ce ratio ne peut pas être lu, la requête échoue avec un 400 qui réclame les deux.

Types de média en sortie#

Les téléchargements directs portent le type de média associé à l'extension de sortie.

Extension Type de contenu
.pdf application/pdf
.png image/png
.jpeg, .jpg image/jpeg
.heic image/heic
.webp image/webp
.svg image/svg+xml
.json application/json
.xml application/xml
.yaml, .yml application/x-yaml
.csv text/csv
.toml application/toml
.html text/html
.md text/markdown; charset=utf-8
.zip application/zip

Tout ce qui ne figure pas dans cette liste est servi en application/octet-stream.

Entrées et sorties V2#

Les endpoints d'intelligence web raisonnent en sorties plutôt qu'en formats de fichiers.

POST /v2/perceive prend une URL et renvoie n'importe lesquelles d'un ensemble fermé de sorties : markdown, html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links, images, structured. La valeur par défaut est ["markdown", "structured"]. Tout sauf structured est écrit dans le stockage et renvoyé sous forme d'URL de téléchargement signée ; structured revient en ligne dans le corps de la réponse.

POST /v2/ingest/files réutilise telle quelle la liste anything-to-markdown ci-dessus : les mêmes 22 extensions sont donc acceptées et les images rejetées de la même façon. Une seule tâche prend jusqu'à 200 fichiers, chaque nom de fichier faisant au maximum 255 caractères, et la sortie de la tâche est un unique fichier JSONL de chunks.

Comment fonctionne la détection de format#

Les fichiers envoyés sont vérifiés deux fois, et aucune des deux vérifications ne regarde le Content-Type de la requête. Il n'existe nulle part dans l'API de liste blanche MIME pour les envois.

D'abord, l'extension du nom de fichier. Si l'endpoint déclare une liste d'extensions acceptées et que la vôtre n'y figure pas, la requête échoue immédiatement :

{
    "detail": "Invalid file format '.txt' for json-to-xml. Allowed: .json"
}

Ensuite, les octets. L'API inspecte les premiers octets du fichier envoyé et compare ce qu'elle y trouve à ce qu'annonçait l'extension. Elle reconnaît PNG, JPEG, GIF, WebP, HEIC et HEIF, PDF, ainsi que les deux types de conteneurs bureautiques (le conteneur ZIP derrière .docx, .xlsx, .pptx, ODF, iWork et EPUB, et l'ancien conteneur OLE2 derrière .doc, .xls, .ppt).

Les formats texte échappent entièrement à cette inspection. JSON, CSV, XML, YAML, TOML, Markdown, HTML, SVG et le texte brut n'ont pas de signature fiable : leur extension est donc prise au pied de la lettre, et c'est le convertisseur qui signale le problème.

L'inspection est délibérément conservatrice. Elle ne rejette qu'une non-concordance à forte confiance, c'est-à-dire une signature qu'elle reconnaît et qui appartient à un groupe différent de celui annoncé par l'extension. Un fichier .png dont les octets sont un JPEG est rejeté. Les octets qu'elle ne reconnaît pas passent. Une non-concordance renvoie 400 :

{
    "detail": "File content does not match the 'jpeg-to-png' input type."
}
Renommer un fichier ne le convertit pas. Appeler photo.webp photo.png franchit le contrôle d'extension puis échoue au contrôle des octets avec le 400 ci-dessus. Envoyez la vraie extension et choisissez l'endpoint qui lui correspond.

Les noms de fichiers sont réécrits, pas rejetés, sur le chemin du stockage : seul le nom de base survit, .. et les caractères <>:"|?* sont retirés, et les espaces deviennent des tirets bas. Voir ingestion de fichiers pour la clé d'objet obtenue.

Pages liées#

← Rate Limits and Quotas