API
API de conversión de documentos
La API de conversión de documentos es una API HTTPS que acepta un archivo, una URL o HTML en una sola llamada POST /v1/convert/{name} y devuelve Markdown.
La prueba anónima acepta archivos de hasta 10 MB y 25 páginas, con 3 conversiones por IP y hora y 10 al día. Lite empieza en $20 al mes con archivos de hasta 100 MB. Pro cuesta $50 al mes; Max cuesta $100 al mes.
- Una llamada POST /v1/convert/{name} por archivo, URL o texto en línea
- Markdown en la respuesta en 60 segundos, o una conversión para sondear
- El mismo motor de conversión que la aplicación 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_…"Cómo funciona la API de conversión de documentos
Tres pasos desde la clave hasta el Markdown. Cada llamada espera hasta 60 segundos y responde con el resultado; las peticiones más largas o con varios archivos devuelven 202 y una conversión para sondear en lugar de mantener la conexión abierta.
Crea una clave de API
Crea una clave en Ajustes → Desarrolladores (necesita una suscripción activa) y envíala en la cabecera x-api-key.
POST /v1/convert/{name}
Envía un archivo, una URL pública o texto en línea al endpoint de ese formato. Un tipo de entrada por llamada.
Usa el Markdown
Lee la salida de la respuesta, o espera a /v1/conversions/{id} tras un 202.
Respuesta y webhooks
La respuesta de abajo ilustra el contrato de la API usando la salida verificada de un parser DOCX; el identificador de conversión es un marcador de posición. Una conversión terminada devuelve el Markdown con los créditos que costó. Un 202 lleva una cabecera Location a la conversión; sondea con ?wait=, transmite sus eventos o deja que un webhook te avise cuando termine.
{
"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" }
}Suscríbete a conversion.completed y conversion.failed para poder reaccionar en el momento en que termina una conversión larga o con varios archivos, en lugar de sondear. Las entregas se firman con cabeceras de Standard Webhooks.
API de análisis de documentos y API de conversión de Markdown
Los equipos buscan una API de análisis de documentos cuando necesitan extraer estructura de los archivos, y una API de conversión de Markdown cuando la salida tiene que acabar en un prompt o en un almacén. Ambas expresiones describen este servicio. Las páginas específicas de formato, como la api de pdf a markdown y la api de url a markdown, son anclas a esos convertidores: usan los mismos endpoints /v1/convert/{name}.
Endpoints de conversión
POST /v1/convert/{name} —un endpoint por formato— acepta un archivo, una URL o texto y devuelve Markdown, texto, HTML o salida por página.
Claves de API
Claves por cuenta enviadas con la cabecera x-api-key, para que la conversión encaje en cualquier servidor o script.
Varios archivos y webhooks
Envía muchos archivos a una misma llamada de conversión y recibe una sola conversión; los webhooks informan de cada conversion.completed o conversion.failed.
Markdown Render
POST /v1/convert/markdown/html o /markdown/text convierte Markdown de vuelta a HTML o texto plano sin coste en créditos.
Casos de uso
Dónde lo integran los equipos
Ingesta para RAG
Convierte documentos dentro de trabajos de ingesta antes de trocearlos e incrustarlos.
Agentes de IA
Deja que los agentes conviertan archivos arbitrarios en texto limpio a mitad del proceso.
Flujos de contenido
Introduce Markdown en un CMS, un sitio de documentación o una base de conocimiento de forma automática.
Herramientas internas
Añade conversión de documentos a los productos y herramientas internas que ya usas.
Autenticación, uso y límites
- Las claves de API pertenecen a tu cuenta, funcionan solo en /v1 y se envían en la cabecera x-api-key; la cuenta necesita una suscripción Lite, Pro o Max activa
- El uso consume los mismos créditos que la aplicación web: las páginas estándar y de OCR cuestan 1 crédito por página
- Los límites de peticiones por plan son Lite 20, Pro 40 y Max 60 peticiones por minuto
- Idempotency-Key en cada llamada POST /v1/convert/{name}, para que un reintento nunca cobre dos veces
- Todos los endpoints v1, los campos de la petición y la respuesta están documentados en la referencia de la API generada; los fallos usan problem+json con una URI type que resuelve a la página del código de error correspondiente
Guía
Gestionar la finalización
Gestiona tanto la finalización en línea como el procesamiento asíncrono en un cliente de la API de conversión de documentos. Un envío correcto puede devolver un resultado ya completado, mientras que el HTTP 202 indica que el trabajo continúa después de la respuesta. Conserva el identificador de la conversión y usa el endpoint documentado de Location o de estado de la conversión antes de leer las salidas. No indexes directamente en una supuesta primera salida solo porque la petición HTTP haya funcionado. Una conversión completada también puede contener fallos a nivel de archivo, así que inspecciona cada archivo en una petición con varios orígenes. Guarda suficiente contexto para conectar cada resultado devuelto con el origen que envió tu aplicación. Así evitas que una conversión lenta o un fallo parcial se conviertan en silencio en un documento vacío dentro de tu sistema.
Límites de petición frente a límites del plan
La API de conversión de documentos aplica límites tanto a las peticiones como a las cuentas. Una petición multipart puede incluir hasta 100 archivos con un límite conjunto de 100 MB. Una petición por URL acepta hasta 20 orígenes. Tu suscripción controla por separado los créditos, el almacenamiento, los límites por archivo y la concurrencia. Un archivo propio de un plan Pro puede estarlo por su suscripción y a la vez ser demasiado grande para una sola petición multipart; usa para ese caso el flujo de subida por fragmentos documentado. No sortees una petición rechazada dando por hecho que el plan más alto elimina los límites de transporte. Lee el error y usa el método de entrada previsto para el tamaño del origen.
Conservar el contexto del origen
Guarda tu propio identificador de origen junto al identificador de la conversión, para que un resultado se pueda rastrear hasta el trabajo que lo envió. El campo metadata de la API transporta datos aportados por quien llama; no es una promesa de extraer títulos de página, autores o fechas de publicación. Si tu aplicación necesita esos datos, recógelos y verifícalos en un paso separado adecuado. Antes de leer su texto, comprueba si una salida se devuelve en línea o mediante un artefacto referenciado, y conserva el documento original cuando tu flujo necesite una pista de auditoría. Una API de conversión de documentos prepara el contenido para la siguiente etapa, mientras que tu aplicación sigue siendo responsable de asociar ese contenido con su origen y de decidir cuánto tiempo conservarlo.
Probar antes del lanzamiento
Prueba más de un archivo pequeño correcto antes de integrar la API de conversión de documentos en un flujo de producción. Incluye una entrada que requiera finalización asíncrona, un archivo no compatible o dañado, una petición con varios orígenes y resultados mixtos, y una respuesta que tu cliente deba tratar como error de límite. Verifica que tu propia lógica de reintento no vuelva a enviar archivos correctos tras un fallo parcial. Guarda las credenciales de la API en tu servidor y evita ponerlas en código de navegador o en ejemplos públicos. Revisa el Markdown real de los tipos de origen representativos antes de evaluar la recuperación o el comportamiento del modelo posterior. Un cliente que gestiona bien los errores de transporte sigue necesitando comprobaciones a nivel de contenido para demostrar que los documentos resultantes son útiles.
FAQ
Preguntas sobre la API de documento a Markdown
¿Cómo me autentico en la API de conversión de documentos?
Crea una clave de API en tu cuenta y envíala en la cabecera `x-api-key`. Las claves están acotadas a tu cuenta.
¿Cuál es el flujo real de conversión?
POST /v1/convert/{name} con un archivo, una URL pública o texto. El Markdown vuelve en la misma respuesta cuando el documento termina dentro de la ventana de espera; si no, recibes 202 y una conversión sobre la que esperar con GET /v1/conversions/{id}?wait=.
¿La conversión es síncrona?
Por defecto, hasta la ventana de espera: POST /v1/convert/{name} espera un resultado y lo devuelve en línea, o devuelve 202 con una Location cuando la conversión no puede terminar a tiempo. Envía Prefer: respond-async para omitir la espera.
¿A qué eventos me puedo suscribir?
Los webhooks salientes admiten conversion.completed y conversion.failed, para que reacciones en cuanto se resuelve una conversión en lugar de sondear.
¿Qué planes incluyen acceso a la API?
El acceso a la API está disponible en los planes de pago. Consulta la página de precios para ver los límites y créditos actuales de cada plan.
¿Cómo se factura el uso de la API?
Las conversiones por API se descuentan del mismo saldo de créditos que la aplicación web. Las páginas estándar y las de OCR cuestan 1 crédito por página.
¿Dónde encuentro una api de pdf a markdown o una api de url a markdown?
Esas expresiones son páginas de formato, no hosts adicionales. Usa las notas de la api de pdf a markdown en /pdf-to-markdown y las de la api de url a markdown en /url-to-markdown, y luego llama a los mismos endpoints de subida y conversión documentados aquí.
¿Cuáles son los límites de peticiones de las claves de API?
Las peticiones se limitan por cuenta: Lite 20, Pro 40 y Max 60 peticiones por minuto.
Convierte tu primer archivo a Markdown.
Pruébalo gratis: no hace falta registrarse.