API HTTP
Usa el conversor desde scripts, automatizaciones o tu propio software: sube un archivo, espera el resultado y descarga el PDF y el Word. Sin registro y sin clave.
Cómo funciona
- 1
Enviar
Envía el documento por POST (o texto Markdown, o un enlace de GitHub) y añade ?wait=50 para esperar el resultado.
- 2
Esperar
La mayoría de los documentos terminan en segundos. Si tarda más de 50 segundos, primero recibes el id de la tarea; sigue esperando con GET.
- 3
Descargar
files en el resultado incluye un enlace de descarga por archivo, válido 2 horas.
Sin clave
Llámala directamente; la misma cuota gratuita que la página web.
La misma calidad que la página
Estilos, tablas, ecuaciones, referencias y plantillas de Word funcionan.
Muchas entradas
Markdown (con carpeta de imágenes o .zip), Word, LaTeX, PDF, enlaces de GitHub.
Borrado automático
Los resultados se borran a las 2 horas, o al instante con DELETE.
Inicio rápido
Convierte report.md en PDF y Word. Al terminar recibes 200 y los enlaces de descarga en files:
curl -F "file=@report.md" -F 'options={"formats":["pdf","docx"]}' \
"https://mdpdfword.com/api/v1/jobs?wait=50"Si recibes 202 (aún en cola o convirtiendo), sigue esperando con el id de la tarea:
curl "https://mdpdfword.com/api/v1/jobs/JOB_ID?wait=50"Endpoints
| Petición | Qué hace |
|---|---|
POST /api/v1/jobs?wait=50 | Envía una conversión y espera hasta wait segundos (50 como máximo). 200 si terminó, si no 202 con el id de la tarea. |
GET /api/v1/jobs/{job_id}?wait=50 | El estado de la tarea; con wait, espera hasta que termine o se acabe el tiempo. |
DELETE /api/v1/jobs/{job_id} | Borra ahora los archivos del resultado. |
GET /api/v1/info | Estilos disponibles, los límites y la cola actual. |
Campos que se envían (multipart/form-data)
| Campo | Qué hace |
|---|---|
file | Un archivo a convertir; repítelo para el documento y las imágenes, archivos .bib, etc. que usa. También sirve un .zip. |
paths | Opcional: las rutas relativas de los archivos, en el mismo orden (lista JSON), para conservar las carpetas — p. ej. ["report.md", "images/a.png"]. |
markdown | Texto Markdown en lugar de un archivo. |
url | Un archivo Markdown de un repositorio público de GitHub en lugar de un archivo; también se descargan sus imágenes. |
template | Opcional: una plantilla .docx — el resultado sigue su configuración de página, fuentes, estilos, encabezados y pies. |
options | Opciones de conversión (objeto JSON), abajo. |
Opciones de conversión (options)
| Opción | Qué hace |
|---|---|
formats | ["pdf", "docx"] (por defecto), ["pdf"] o ["docx"]; con entrada Word, LaTeX o PDF también ["markdown"] para obtener solo Markdown editable. |
theme | Nombre del estilo, business por defecto; las opciones están en /api/v1/info. |
toc | true: añade un índice. |
number_sections | true / false: numera los títulos. |
docx_fonts | windows (por defecto) o mac: los nombres de fuentes CJK en Word. |
main | Con varios documentos subidos, el que se convierte (ruta relativa). |
filename | Nombre de archivo del texto markdown enviado. |
track_changes | Entrada Word: accept (por defecto) o reject para los cambios controlados. |
keep_source_format | Entrada Word y LaTeX: false usa en su lugar el formato del estilo elegido. |
pdf_ocr | Entrada PDF: true significa que aceptas que el PDF se envíe a SoMark para el reconocimiento avanzado (ver Privacidad). Sin esta opción no se envía nada. |
El resultado
status es queued, running, done o error (entonces error y code dicen por qué). warnings enumera lo que conviene revisar, como imágenes que faltan.
{
"ok": true,
"job_id": "Vq3…",
"status": "done",
"version": 3,
"main": "report.md",
"elapsed": 4.2,
"files": [
{
"format": "pdf",
"name": "report.pdf",
"size": 182340,
"url": "https://mdpdfword.com/files/results/…/report.pdf",
"file_id": "…"
},
{
"format": "docx",
"name": "report.docx",
"size": 48211,
"url": "https://mdpdfword.com/files/results/…/report.docx",
"file_id": "…"
}
],
"warnings": [],
"pdf_pages": 3,
"expires_in_minutes": 120
}Ejemplo en Python
import json
import requests
API = "https://mdpdfword.com/api/v1/jobs"
with open("report.md", "rb") as f:
job = requests.post(API, params={"wait": 50}, files={"file": f},
data={"options": json.dumps({"formats": ["pdf", "docx"]})},
timeout=70).json()
while job.get("status") in ("queued", "running"):
job = requests.get(f"{API}/{job['job_id']}", params={"wait": 50}, timeout=70).json()
if not job.get("ok"):
raise SystemExit(f"{job.get('code')}: {job.get('error')}")
for out in job["files"]:
with open(out["name"], "wb") as f:
f.write(requests.get(out["url"], timeout=120).content)Códigos de error
| code | Qué hace |
|---|---|
bad_request / no_document | 400: parámetros incorrectos, o no se encontró ningún documento que convertir. |
file_too_big / total_too_big / too_many_files | 413: se supera el límite de tamaño o de número de archivos. |
too_many_active / rate_hour / rate_limited | 429: demasiadas a la vez o se superó la cuota por hora; reintenta más tarde (si hay un encabezado Retry-After, espera esos segundos). |
busy / storage_full | 503: el servidor está ocupado; reintenta en unos minutos. |
not_found | 404: la tarea no existe o ha caducado. |
pdf_scanned | La tarea falló: PDF escaneado; indica pdf_ocr: true para reconocerlo. |
timeout / conversion_failed | La tarea falló: el documento es demasiado complejo o tiene un error; error lo explica. |
Límites
Los mismos que en la página web: por dirección IP, 2 a la vez como máximo y 30 por hora; 20 MB por archivo, 60 MB y 300 archivos en total; hasta 5 minutos por conversión; resultados guardados 2 horas.
El servicio funciona en una sola máquina. Para que quienes usan la página nunca esperen detrás de scripts, las peticiones de la API comparten parte de los turnos de conversión, y la cola puede ser más larga cuando hay mucha carga. Envía los documentos de uno en uno, no en lotes paralelos.
Privacidad
Los archivos subidos solo se usan para esta conversión, y los resultados se borran a las 2 horas. Los PDF se leen solo en el servidor de este sitio; solo si la petición indica "pdf_ocr": true se envía el PDF al servicio externo SoMark para el reconocimiento avanzado — no lo indiques con archivos sensibles. Consulta la política de privacidad. Política de privacidad
Preguntas y respuestas
¿Necesito registrarme o una clave de API?
No. Llámala directamente; comparte la cuota gratuita de la página web.
¿Puedo llamarla desde una página web (JavaScript en el navegador)?
No. Para que otros sitios no puedan enviar aquí los archivos de sus visitantes, la API no permite llamadas entre sitios. Llámala desde un servidor o un script.
¿En qué se diferencia de MCP?
MCP es para asistentes de IA como Claude Code y Codex; la API HTTP es para scripts y programas. La calidad y la cuota son las mismas.
¿Cambiará la API?
/api/v1 es estable: pueden añadirse campos, pero los existentes conservan su significado. /api/jobs, que usa la página web internamente, no está garantizado — no dependas de él.