API Documentation

API de Conversión de Páginas Web#

Los endpoints de páginas web renderizan URLs en vivo en un navegador real y las convierten en PDFs, capturas de pantalla PNG de página completa o Markdown limpio con estilo GitHub-Flavored. Los endpoints de una sola URL se ejecutan de forma síncrona (o asíncrona en lotes), mientras que los endpoints de sitio web rastrean un sitio completo (mediante análisis del sitemap o un rastreo completo en anchura, breadth-first) y agrupan cada página en un único archivo ZIP. Todos los endpoints comparten el mismo pipeline de navegador: descarte de banners de cookies, desplazamiento para carga diferida (lazy-load), gestión de encabezados fijos (sticky header) y compatibilidad con páginas protegidas por HTTP Basic Auth, cookies inyectadas o cabeceras personalizadas.

Conversiones admitidas#

Conversión Endpoint Descripción
URL a PDF POST /v1/convert/url-to-pdf Convierte cualquier URL de acceso público en un PDF de alta fidelidad, con salida continua de una sola página o paginada, tamaños de página personalizados, encabezados/pies de página y modo asíncrono por lotes.
URL a Captura de Pantalla POST /v1/convert/url-to-screenshot Captura una captura de pantalla de página completa de cualquier URL como un PNG de alta fidelidad, redimensionando el viewport a la altura real del contenido para que toda la página quede en una sola imagen.
URL a Markdown POST /v1/convert/url-to-markdown Convierte una página web en Markdown limpio con estilo GitHub-Flavored y frontmatter YAML, usando extracción Readability para eliminar el contenido repetitivo (boilerplate). Está diseñado para pipelines de ingesta de LLM y RAG.
Sitio Web a PDF POST /v1/convert/website-to-pdf Rastrea un sitio web completo mediante sitemap o un rastreo completo en anchura, convierte cada página descubierta a PDF y agrupa los resultados en un único archivo ZIP.
Sitio Web a Captura de Pantalla POST /v1/convert/website-to-screenshot Descubre todas las páginas de un sitio web mediante sitemap o un rastreo completo y captura un PNG de página completa de cada una, entregado como un único archivo ZIP.

Convenciones compartidas#

  • Autenticación: todos los endpoints aceptan una clave privada en la cabecera X-API-Key; los tres endpoints de una sola URL también aceptan tokens JWT Bearer de clave pública (restringidos a una sola URL, modo síncrono y descarga directa), mientras que los endpoints de sitio web requieren una clave privada. Consulta Autenticación.
  • Síncrono vs. asíncrono: los endpoints de una sola URL se ejecutan de forma síncrona por defecto y cambian a asíncrono (async_mode=true, HTTP 202 con un batch_id) para lotes; los endpoints de sitio web siempre son asíncronos. Consulta GET /v1/convert/batch/{batch_id} para los resultados. Consulta Trabajos síncronos y asíncronos.
  • Respuestas: las conversiones completadas devuelven una URL de descarga prefirmada y object_key; los endpoints de una sola URL pueden devolver en su lugar los bytes de salida en bruto con direct_download=true.
  • Parámetros de navegador y renderizado: viewport_width/viewport_height, handle_cookies, enable_scroll, load_media, wait_for_images y handle_sticky_header se comparten entre los cinco endpoints, al igual que las opciones auth, cookies (máx. 50) y headers (máx. 20) para páginas protegidas. Consulta Trabajos síncronos y asíncronos.
  • Errores y restricciones por plan: todos los endpoints usan los mismos códigos de estado: 400 para entrada inválida, 401 para credenciales incorrectas, 402 para límites de cuota o almacenamiento, y 403 para funciones restringidas por plan (asíncrono, webhooks, salida ZIP, basic auth, captura de sitio web). Consulta Códigos de Error.

Preguntas frecuentes#

¿Qué endpoint debo usar para una sola página frente a un sitio web completo?#

Usa url-to-pdf, url-to-screenshot o url-to-markdown para una URL o una lista explícita de URLs. Usa website-to-pdf o website-to-screenshot cuando quieras que la API descubra las páginas por sí misma mediante análisis de sitemap.xml o un rastreo completo en anchura, y devuelva todo en un único ZIP.

¿Pueden estos endpoints convertir páginas protegidas por inicio de sesión?#

Sí, en planes con acceso a basic auth. Los cinco endpoints aceptan un objeto auth para HTTP Basic Auth, hasta 50 cookies inyectadas para acceso basado en sesión, y hasta 20 headers personalizadas. Estas opciones resultan útiles para sitios de staging, páginas solo para miembros y paneles.

¿Cómo obtengo el resultado de un trabajo asíncrono?#

Los trabajos asíncronos devuelven HTTP 202 con un batch_id de inmediato. Consulta GET /v1/convert/batch/{batch_id} con tu clave privada para conocer los estados por URL y las URLs de descarga prefirmadas, proporciona un callback_url para recibir un POST de webhook al completarse, o confía en el email de finalización enviado a notification_email (el propietario del proyecto por defecto).

← Conversion Matrix url-to-pdf →