API
API de conversion de documents
L'API de conversion de documents est une API HTTPS qui accepte un fichier, une URL ou du HTML en un seul appel POST /v1/convert/{name} et renvoie du Markdown.
L'essai anonyme accepte des fichiers jusqu'à 10 MB et 25 pages, avec 3 conversions par IP et par heure et 10 par jour. Lite commence à $20 par mois avec des fichiers jusqu'à 100 MB. Pro coûte $50 par mois ; Max coûte $100 par mois.
- Un appel POST /v1/convert/{name} par fichier, URL ou texte en ligne
- Le Markdown dans la réponse en 60 secondes, ou une conversion à interroger
- Le même moteur de conversion que l'application web
# Upload a local file; Markdown comes back in the same response
curl -X POST https://api.markitdown.ai/v1/convert/pdf \
-H "x-api-key: mdai_…" \
-F file=@nist-cswp-29-csf-2.0.pdf
# Or convert a public web page
curl -X POST https://api.markitdown.ai/v1/convert/url \
-H "x-api-key: mdai_…" \
-H "content-type: application/json" \
-d '{"url":"https://markitdown.ai/blog/why-pdfs-break-llms"}'
# Took longer than the wait window? Long-poll the conversion
curl "https://api.markitdown.ai/v1/conversions/<id>?wait=100" \
-H "x-api-key: mdai_…"Comment fonctionne l'API de conversion de documents
Trois étapes, de la clé au Markdown. Chaque appel attend jusqu'à 60 secondes et répond avec le résultat ; les requêtes plus longues ou multi-fichiers renvoient 202 et une conversion à interroger au lieu de garder la connexion ouverte.
Créez une clé d'API
Créez une clé dans Réglages → Développeurs (un abonnement actif est requis) et envoyez-la dans l'en-tête x-api-key.
POST /v1/convert/{name}
Envoyez un fichier, une URL publique ou du texte en ligne au point d'accès de ce format. Un seul type d'entrée par appel.
Utilisez le Markdown
Lisez la sortie depuis la réponse, ou attendez sur /v1/conversions/{id} après un 202.
Réponse et webhooks
La réponse ci-dessous illustre le contrat de l'API à l'aide d'une sortie d'analyseur DOCX vérifiée ; l'identifiant de conversion est un espace réservé. Une conversion terminée renvoie le Markdown avec les crédits qu'elle a coûtés. Un 202 porte un en-tête Location vers la conversion ; interrogez-la avec ?wait=, diffusez ses événements ou laissez un webhook vous prévenir quand elle aboutit.
{
"id": "cnv_3f7c…",
"object": "conversion",
"name": "word",
"status": "completed",
"files": [ { "outputs": [ { "format": "markdown", "content": "## Review Findings\n\nRisk ratings follow the standard High / Medium / Low scale defined in the vendor risk management policy.\n\n| Vendor | Risk Rating | Finding | Owner |\n| --- | --- | --- | --- |\n| CloudScan OCR | Medium | No documented data retention limit on uploaded scans | Security |\n| PayBridge | Low | SOC 2 Type II renewed; no open items | Finance |\n| LingoTrans API | High | Sub-processor list not disclosed on request | Legal |\n| ArchiveNow Storage | Medium | Encryption at rest confirmed; key rotation overdue | Security |\n" } ] } ],
"usage": { "credits_charged": 1 }
}POST https://your-app.example.com/webhooks
{
"type": "conversion.completed",
"data": { "id": "cnv_3f7c…", "object": "conversion", "status": "completed" }
}Abonnez-vous à conversion.completed et conversion.failed pour réagir dès qu'une conversion longue ou multi-fichiers aboutit, au lieu d'interroger en boucle. Les livraisons sont signées avec les en-têtes Standard Webhooks.
API d'analyse de documents et API de conversion Markdown
Les équipes cherchent une API d'analyse de documents quand elles ont besoin de tirer de la structure des fichiers, et une API de conversion Markdown quand la sortie doit atterrir dans un prompt ou un coffre. Les deux expressions décrivent ce service. Les pages propres à un format, comme l'api pdf vers markdown et l'api url vers markdown, sont des ancres vers ces convertisseurs — elles utilisent les mêmes points d'accès /v1/convert/{name}.
Points d'accès de conversion
POST /v1/convert/{name} — un point d'accès par format — accepte un fichier, une URL ou du texte et renvoie du Markdown, du texte, du HTML ou une sortie par page.
Clés d'API
Des clés par compte envoyées via l'en-tête x-api-key, pour que la conversion s'intègre à n'importe quel serveur ou script.
Fichiers multiples et webhooks
Envoyez de nombreux fichiers à un même appel de conversion et recevez une seule conversion ; les webhooks signalent chaque conversion.completed ou conversion.failed.
Markdown Render
POST /v1/convert/markdown/html ou /markdown/text reconvertit le Markdown en HTML ou en texte brut sans coût en crédits.
Cas d'usage
Où les équipes l'intègrent
Ingestion RAG
Convertissez des documents au sein des tâches d'ingestion avant le découpage et la vectorisation.
Agents IA
Laissez les agents transformer des fichiers quelconques en texte propre au milieu du pipeline.
Pipelines de contenu
Alimentez automatiquement un CMS, un site de documentation ou une base de connaissances en Markdown.
Outils internes
Ajoutez la conversion de documents aux produits et aux outils de back-office que vous utilisez déjà.
Authentification, usage et limites
- Les clés d'API appartiennent à votre compte, fonctionnent uniquement sur /v1 et s'envoient dans l'en-tête x-api-key — le compte doit avoir un abonnement Lite, Pro ou Max actif
- L'usage consomme les mêmes crédits que l'application web — les pages standard et OCR coûtent 1 crédit par page
- Les limites de débit par forfait sont Lite 20, Pro 40 et Max 60 requêtes par minute
- Idempotency-Key sur chaque appel POST /v1/convert/{name}, pour qu'une relance ne facture jamais deux fois
- Chaque point d'accès v1, champ de requête et réponse est documenté dans la référence de l'API générée ; les échecs utilisent problem+json avec une URI type qui pointe vers la page du code d'erreur correspondante
Guide
Gérer l'aboutissement
Gérez à la fois l'aboutissement en ligne et le traitement asynchrone dans un client de l'API de conversion de documents. Une soumission réussie peut renvoyer un résultat déjà terminé, tandis qu'un HTTP 202 indique que le travail continue après la réponse. Conservez l'identifiant de conversion et utilisez le point d'accès documenté Location ou l'état de la conversion avant de lire les sorties. N'indexez pas directement dans une supposée première sortie simplement parce que la requête HTTP a réussi. Une conversion terminée peut aussi contenir des échecs au niveau des fichiers, alors inspectez chaque fichier dans une requête multi-source. Stockez assez de contexte pour relier chaque résultat renvoyé à la source soumise par votre application. Vous évitez ainsi qu'une conversion lente ou un échec partiel ne devienne silencieusement un document vide dans votre système.
Limites de requête contre limites de forfait
L'API de conversion de documents applique des limites à la fois aux requêtes et aux comptes. Une requête multipart peut inclure jusqu'à 100 fichiers avec une limite combinée de 100 MB. Une requête par URL accepte jusqu'à 20 sources. Votre abonnement contrôle séparément les crédits, le stockage, les limites par fichier et la concurrence. Un fichier autorisé par un forfait Pro peut être trop gros pour une seule requête multipart ; utilisez dans ce cas le flux d'import par fragments documenté. Ne contournez pas une requête rejetée en supposant que le forfait le plus élevé supprime les limites de transport. Lisez l'erreur et utilisez la méthode d'entrée prévue pour la taille de la source.
Conserver le contexte de la source
Gardez votre propre identifiant de source à côté de l'identifiant de conversion, pour qu'un résultat puisse être rattaché à la tâche qui l'a soumis. Le champ metadata de l'API transporte des données fournies par l'appelant ; ce n'est pas une promesse d'extraire des titres de page, des auteurs ou des dates de publication. Si votre application a besoin de ces informations, collectez-les et vérifiez-les dans une étape distincte appropriée. Avant de lire son texte, vérifiez si une sortie est renvoyée en ligne ou via un artefact référencé, et conservez le document original quand votre flux a besoin d'une piste d'audit. Une API de conversion de documents prépare le contenu pour l'étape suivante, tandis que votre application reste responsable d'associer ce contenu à sa source et de décider combien de temps le conserver.
Tester avant la mise en production
Testez plus d'un petit fichier réussi avant d'intégrer l'API de conversion de documents dans un flux de production. Incluez une entrée qui exige un aboutissement asynchrone, un fichier non pris en charge ou endommagé, une requête multi-source aux résultats mitigés et une réponse que votre client doit traiter comme une erreur de limite. Vérifiez que votre propre logique de relance ne soumet pas à nouveau des fichiers réussis après un échec partiel. Gardez les identifiants d'API sur votre serveur et évitez de les placer dans du code de navigateur ou des exemples publics. Examinez le Markdown réel des types de source représentatifs avant d'évaluer la recherche ou le comportement du modèle en aval. Un client qui gère correctement les erreurs de transport a encore besoin de contrôles au niveau du contenu pour prouver que les documents obtenus sont utiles.
FAQ
Questions sur l'API de conversion de documents
Comment m'authentifier auprès de l'API de conversion de documents ?
Créez une clé d'API dans votre compte et envoyez-la dans l'en-tête `x-api-key`. Les clés sont limitées à votre compte.
Quel est le vrai flux de conversion ?
POST /v1/convert/{name} avec un fichier, une URL publique ou du texte. Le Markdown revient dans la même réponse quand le document se termine dans la fenêtre d'attente ; sinon, vous recevez 202 et une conversion à attendre avec GET /v1/conversions/{id}?wait=.
La conversion est-elle synchrone ?
Par défaut, jusqu'à la fenêtre d'attente : POST /v1/convert/{name} attend un résultat et le renvoie en ligne, ou renvoie 202 avec un Location quand la conversion ne peut pas finir à temps. Envoyez Prefer: respond-async pour ignorer l'attente.
À quels événements puis-je m'abonner ?
Les webhooks sortants prennent en charge conversion.completed et conversion.failed, pour que vous réagissiez dès qu'une conversion aboutit au lieu d'interroger en boucle.
Quels forfaits incluent l'accès à l'API ?
L'accès à l'API est disponible sur les forfaits payants. Consultez la page des tarifs pour les limites et crédits actuels de chaque forfait.
Comment l'usage de l'API est-il facturé ?
Les conversions par API sont déduites du même solde de crédits que l'application web. Les pages standard et OCR coûtent 1 crédit par page.
Où trouver une api pdf vers markdown ou une api url vers markdown ?
Ces expressions sont des pages de format, pas des hôtes supplémentaires. Utilisez les notes de l'api pdf vers markdown sur /pdf-to-markdown et celles de l'api url vers markdown sur /url-to-markdown, puis appelez les mêmes points d'accès d'import et de conversion documentés ici.
Quelles sont les limites de débit des clés d'API ?
Les requêtes sont limitées par compte : Lite 20, Pro 40 et Max 60 requêtes par minute.
Convertissez votre premier fichier en Markdown.
Essai gratuit — sans inscription.