API de Web Scraping para Markdown, Capturas de Pantalla y Datos Estructurados#

POST /v2/perceive es la API de web scraping de EnConvert: renderiza una URL una vez en un navegador headless real, con JavaScript ejecutado y contenido de carga diferida (lazy load) ya cargado, y te devuelve todos los outputs que pidas a partir de ese único render: Markdown limpio (por defecto solo el contenido principal, sin el chrome del sitio), HTML limpio o en bruto, una captura de pantalla, un PDF, el inventario de enlaces e imágenes, y datos estructurados (metadatos de la página, JSON-LD, encabezados, tablas). Los outputs de archivo vuelven como URLs de descarga pre-firmadas de corta duración, el bloque estructurado va inline, y los lotes de más de 10 URLs se ejecutan de forma asíncrona detrás de un job_id que se consulta por polling. Una sola solicitud reemplaza toda una pila de llamadas separadas: url-to-markdown, url-to-screenshot, url-to-pdf, más tu propio scraping.

Este es el llamado más pequeño y útil. Envía una URL y recibe Markdown limpio junto con los metadatos estructurados de la página:

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "outputs": ["markdown", "structured"]
  }'

La respuesta incluye una URL de descarga pre-firmada para el archivo Markdown y el bloque estructurado inline:

{
    "operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "status": "completed",
    "url": "https://example.com/pricing",
    "url_final": "https://example.com/pricing",
    "content_hash": "9f2b8c1a...d4e5",
    "render_quality": 0.93,
    "cache_hit": false,
    "outputs": {
        "markdown": {
            "url": "https://spaces.example.com/...signed...",
            "object_key": "env/files/4127/v2-perceive/per_3f9a..._markdown.md",
            "size_bytes": 8421,
            "content_type": "text/markdown; charset=utf-8",
            "expires_in": 900
        }
    },
    "structured": {
        "metadata": {
            "title": "Pricing",
            "description": "Simple, usage-based pricing."
        },
        "structured_data": [
            {"@type": "Product", "name": "Studio", "offers": {"price": "99"}}
        ]
    },
    "extraction_tier": "heuristic",
    "tokens": {"input": 0, "output": 0},
    "cost_cents": 0.0,
    "duration_ms": 6230,
    "warnings": []
}

Endpoints#

Content-Type: application/json en cada POST.

Autenticación#

Autentícate con una clave privada en el encabezado X-API-Key para llamadas de servidor a servidor. Este es el flujo que usan los ejemplos a continuación.

X-API-Key: sk_your_private_key

Las claves públicas con un token JWT bearer también funcionan, usando el mismo flujo que cualquier otro endpoint: genera un token con tu clave pk_ y luego envíalo como Authorization: Bearer <token>. El flujo completo, incluido el bloqueo por dominio y la renovación de tokens, está en la guía de autenticación.

Cada clave de API tiene una lista blanca de endpoints permitidos. Si /v2/perceive no está en la lista de la clave, la solicitud se rechaza con 403.

Cómo funciona perceive#

Una solicitud dispara un render de navegador a través de un singleton compartido de Chrome headless, y luego materializa cada output a partir de ese render. Nunca pagas por la misma página dos veces en una sola llamada.

1. Render. La página se obtiene a través de un fallback automático de múltiples motores: primero una huella TLS de navegador real y rápida, escalando a Chrome headless cuando la página está bloqueada o necesita JavaScript, y una vez más a un render reforzado con técnicas de sigilo (stealth) cuando una página sigue pareciendo bloqueada por protección anti-bot, de modo que más páginas del mundo real devuelven contenido utilizable. En el navegador, se descartan los banners de cookies, se hace scroll en la página para disparar el contenido de carga diferida, se gestionan los encabezados fijos (sticky), y se da tiempo a que las imágenes carguen. Es el mismo pipeline de captura que impulsa el endpoint url-to-pdf.
2. Materializar. A partir del DOM renderizado, perceive construye todo lo que hayas indicado en outputs: Markdown, HTML limpio/en bruto, enlaces, imágenes, una captura de pantalla, un PDF. El DOM se normaliza antes para que el Markdown refleje lo que ve un lector: los fences de código conservan su lenguaje, los enlaces de tarjeta su estructura, y los elementos de interfaz se eliminan bajo only_main_content. Consulta Calidad del Markdown.
3. Extraer. Si solicitaste el output structured, perceive ejecuta una pasada heurística para obtener metadatos de la página, JSON-LD, encabezados y tablas. Si además envías un schema y tu plan incluye el nivel LLM, una pasada asistida por LLM completa el schema cuando la pasada heurística se queda corta.
4. Puntuar. Un puntaje de calidad de render (0.0–1.0) distingue un render real de uno fallido. Los puntajes por debajo de 0.40 indican un render fallido: una página anti-bot, un muro de inicio de sesión, una página de error HTTP, un soft 404 o un cascarón vacío. Consulta deductions para conocer el motivo y status_code para el estado del servidor de origen.

Los outputs binarios y de texto (Markdown, HTML, capturas de pantalla, PDFs, el JSON de enlaces e imágenes) se suben al almacenamiento y se devuelven como URLs pre-firmadas que expiran a los 15 minutos. El bloque structured se devuelve inline en el JSON. Vuelve a obtener cualquier operación con GET /v2/perceive/{operation_id} para conseguir un nuevo conjunto de URLs firmadas.

Parámetros de la solicitud#

La validación es estricta: una clave de solicitud que el schema no conoce se rechaza con 422 nombrando el campo afectado. Las claves desconocidas nunca se ignoran silenciosamente. Cada cuerpo 422 incluye además un array errors de nivel superior con mensajes legibles por humanos, junto a la lista detail legible por máquinas.

Básicos#

Salidas#

outputs acepta cualquier combinación de estos nombres:

Calidad del Markdown#

Antes de convertir la página, el DOM renderizado se normaliza para que el Markdown refleje lo que ve un lector y no cómo se construyó la página. Esto se ejecuta en cada render, así que el resultado no depende de qué estrategia de extracción gane para una página concreta.

Se aplica siempre, en ambos modos de only_main_content:

• Los fences de código conservan su lenguaje. El lenguaje se lee de la convención que use el sitio (class="language-python", data-lang, un atributo language desnudo o un wrapper del resaltador) y se normaliza, de modo que llega ```python en lugar de un fence pelado.
• Los enlaces de tarjeta siguen siendo legibles. Un enlace que envuelve un encabezado y una descripción se convierte en un título enlazado seguido de su descripción, en lugar de un único enlace amontonado como [DatabaseSupabase provides a full Postgres database...]. La URL de destino se conserva.
• Los encabezados se mantienen en una sola línea. Un encabezado cuyo texto vive dentro de un elemento anidado ya no emite un ## pelado con el texto varado debajo.
• Los elementos adyacentes ya no se concatenan. Los layouts que separan sus elementos con CSS en vez de con espacios producían YesNo y EvaluationDeploymentProduction; ahora se leen como palabras separadas.
• Se eliminan los caracteres invisibles: espacios de ancho cero usados como etiquetas de anclaje, guiones suaves y glifos del Área de Uso Privado de las fuentes de iconos, que llegan como tokens no imprimibles.
• Se descartan los elementos vacíos: elementos <i> que solo contenían un icono y se renderizaban como un __ suelto, y enlaces cuya etiqueta está vacía.

Además, con only_main_content: true:

• Se eliminan los controles de interfaz: botones, tiras de pestañas, pistas de atajos de teclado, acciones «Copy page» / «On this page» y widgets de valoración «¿Te ha resultado útil esta página? Sí/No». Un control que contiene contenido real (una pregunta de FAQ, el cuerpo de una tarjeta clicable) se conserva.
• Se elimina el texto destinado solo a lectores de pantalla: enlaces de salto y las etiquetas «Section titled ...» que muchos temas de documentación añaden a cada encabezado.
• Se respeta el contenido que el sitio declara como no-contenido: bloques marcados con data-nosnippet, data-pagefind-ignore o data-noindex, salvo que contengan encabezados o código.
• Se colapsan los bloques duplicados: los diseños responsive que envían una copia de escritorio y otra móvil de la misma barra, y los carruseles que pre-renderizan cada fotograma, aparecen una sola vez.
• Se descartan las migas de pan y las etiquetas de antetítulo situadas sobre el título de la página.

El contenido diferido se conserva deliberadamente: un panel de pestaña inactivo dentro de la región de contenido guarda un ejemplo de código real (el ejemplo de Python en una pestaña, el de JavaScript en otra), de modo que ambos llegan al Markdown y no solo la pestaña que por casualidad estuviera seleccionada en el momento del render.

Renderizado y espera#

Solicitudes autenticadas y personalizadas#

Extracción estructurada#

Cuando structured está en outputs, la lista extract controla qué campos extrae perceive. Si no pides nada, se usa por defecto metadata y structured_data.

Para ser claros: prices, contacts y technologies son nombres reservados. Si solicitas uno hoy, no da error: el nombre cae en el array warnings y se elimina de structured.

Extracción guiada por schema#

Envía un schema para extraer campos específicos hacia structured.extracted:

{
    "url": "https://example.com/product/widget",
    "outputs": ["markdown", "structured"],
    "schema": {
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "price": {"type": "number"},
            "in_stock": {"type": "boolean"}
        }
    }
}

El nivel de extracción asistida por LLM completa el schema, y solo se activa cuando se cumplen todas estas condiciones: enviaste un schema, tu plan incluye el nivel LLM (Indie en adelante), la página no fue puntuada como bloqueada, y la pasada heurística dejó campos del schema vacíos. Cuando se ejecuta, extraction_tier es "llm", y tokens y cost_cents reportan lo que costó esa extracción; en caso contrario, extraction_tier es "heuristic" y ambos son cero.

Nota. La extracción por schema tiene un límite estricto para proteger tu factura: una única extracción está limitada por solicitud, y el gasto del proyecto consume tu saldo mensual de créditos de IA ($5 / $15 / $40 al mes en Indie / Studio / Production; los créditos no usados se acumulan). La extracción con LLM consume créditos, no ops. Si se alcanza un límite o se agota el saldo, perceive devuelve el resultado heurístico con una nota en warnings en lugar de gastar de más. En un plan sin el nivel LLM, solo obtienes datos structured heurísticos.

Respuesta#

Tanto POST /v2/perceive como GET /v2/perceive/{operation_id} devuelven el mismo objeto.

Recuperar una operación#

Las URLs firmadas expiran a los 15 minutos. Para descargar un output más tarde, vuelve a obtener la operación. Perceive vuelve a firmar cada URL a partir de las claves de objeto almacenadas. No se produce ningún re-render, así que esto no consume ops.

curl https://api.enconvert.com/v2/perceive/per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7 \
  -H "X-API-Key: sk_your_private_key"

Un ID de operación desconocido, o uno que pertenece a otro proyecto, devuelve 404. La existencia nunca se filtra entre proyectos.

Descarga directa#

Por defecto, cada output de archivo vuelve como una URL pre-firmada que obtienes en una segunda solicitud. Define direct_download: true en el POST para saltarte el sobre: el cuerpo de la respuesta HTTP es los bytes del artefacto, sin JSON, sin URL firmada y sin segunda descarga. La solicitud debe producir exactamente un output que genere artefacto (outputs: ["markdown"], outputs: ["pdf"], …), de lo contrario se rechaza con 400. Los metadatos que habrían ido en el JSON viajan en cambio en encabezados de respuesta: Content-Disposition, X-Operation-Id, X-Object-Key, X-Cache-Hit, X-Render-Quality, X-Source-Status-Code, X-Content-Hash y X-Warnings-Count.

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/post",
    "outputs": ["markdown"],
    "direct_download": true
  }' \
  -o post.md

Los endpoints GET transmiten los artefactos almacenados de la misma manera:

• GET /v2/perceive/{operation_id}?direct_download=true&output=markdown transmite un artefacto de una operación pasada. output es obligatorio cuando la operación produjo más de un artefacto. Un artefacto que superó la ventana de retención de tu plan responde 410.
• GET /v2/perceive/batch/{job_id}?direct_download=true transmite el ZIP del lote. Vale para lotes con output_mode: "zip" cuyo archivo ya está listo; de lo contrario responde 400.

direct_download es solo para URLs individuales: POST /v2/perceive/batch lo rechaza con 422. Define output_mode como "zip" y descarga el archivo comprimido. Consulta Percepción por lotes.

Percepción por lotes#

POST /v2/perceive/batch percibe una lista de URLs que comparten un mismo bloque options. Cada URL se renderiza a través del mismo pipeline que una llamada individual y genera su propia fila de operación.

curl -X POST https://api.enconvert.com/v2/perceive/batch \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/a",
      "https://example.com/b",
      "https://example.com/c"
    ],
    "options": {"outputs": ["markdown"]},
    "output_mode": "manifest"
  }'

Los lotes de 10 URLs o menos se ejecutan inline y responden 200 con todos los resultados completados. Los lotes más grandes responden 202 con un job_id; las URLs se procesan una a la vez y las consultas por polling para obtener los resultados:

curl https://api.enconvert.com/v2/perceive/batch/{job_id} \
  -H "X-API-Key: sk_your_private_key"

La respuesta del lote reporta el progreso agregado y lleva un resultado completo de perceive por cada URL una vez renderizada:

{
    "job_id": "bat_8c1a...",
    "status": "partial",
    "output_mode": "manifest",
    "total": 3,
    "completed": 2,
    "failed": 1,
    "pending": 0,
    "items": [
        {"operation_id": "per_...", "status": "completed", "url": "https://example.com/a"},
        {"operation_id": "per_...", "status": "completed", "url": "https://example.com/b"},
        {"operation_id": "per_...", "status": "failed", "url": "https://example.com/c"}
    ]
}

status es queued, processing, completed, failed, partial (algunas URLs tuvieron éxito, otras fallaron), o canceled. Define output_mode como zip para agrupar todos los artefactos en un único ZIP, devuelto en el campo zip cuando el lote termina.

Durable y reanudable#

Los lotes son resistentes a reinicios. Si el servicio se reinicia mientras un lote está en curso, el lote se reanuda automáticamente y solo vuelve a renderizar las URLs que no habían terminado, así que las URLs ya completadas conservan sus artefactos. Nunca necesitas reenviar un lote por culpa de un reinicio.

Cancelar un lote#

DELETE /v2/perceive/batch/{job_id} cancela un lote en ejecución. El worker se detiene entre URLs, así que las URLs ya renderizadas conservan sus resultados y el resto queda sin iniciar. La llamada es idempotente, así que cancelar un lote que ya terminó simplemente devuelve su estado actual, y el status del lote pasa a canceled.

curl -X DELETE https://api.enconvert.com/v2/perceive/batch/{job_id} \
  -H "X-API-Key: sk_your_private_key"

Caché#

cache_mode controla cómo perceive trata su caché de resultados de 1 hora, indexada por tu proyecto, la URL y las opciones de la solicitud que afectan al render.

Vale la pena aclarar: un acierto de caché igual cuenta como una op contra tu cuota mensual de ops. La cuota mide operaciones, no renders de navegador, así que la caché te ahorra tiempo de render, no ops.

Ejemplos de código#

curl: Solo Markdown#

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/post",
    "outputs": ["markdown"]
  }'

curl: Markdown más datos estructurados#

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "outputs": ["markdown", "structured"],
    "extract": ["metadata", "structured_data", "tables"]
  }'

curl: Outputs completos más PDF#

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/report",
    "outputs": ["markdown", "html_cleaned", "screenshot_full_page", "pdf"],
    "pdf_options": {"format": "A4", "print_background": true}
  }'

Python#

import requests

response = requests.post(
    "https://api.enconvert.com/v2/perceive",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": "https://example.com/pricing",
        "outputs": ["markdown", "structured"],
        "extract": ["metadata", "tables"],
    },
)
response.raise_for_status()
data = response.json()

# Download the Markdown artifact from its signed URL
markdown_url = data["outputs"]["markdown"]["url"]
markdown_text = requests.get(markdown_url).text

print(data["structured"])
print(markdown_text)

Node.js#

const res = await fetch("https://api.enconvert.com/v2/perceive", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_your_private_key"
    },
    body: JSON.stringify({
        url: "https://example.com/pricing",
        outputs: ["markdown", "structured"],
        extract: ["metadata", "tables"]
    })
});

const data = await res.json();

// Download the Markdown artifact from its signed URL
const markdownText = await fetch(data.outputs.markdown.url).then(r => r.text());

console.log(data.structured);
console.log(markdownText);

Si llamas a EnConvert desde Claude, Cursor u otro cliente MCP, la misma capacidad se expone como la herramienta perceive_url. Consulta la página del servidor MCP.

Respuestas de error#

Las claves de solicitud desconocidas se rechazan con un 422 que nombra el campo, en /v2/perceive, /v2/perceive/batch, /v2/discover y /v2/lookup por igual. Nunca se ignoran silenciosamente. Cada cuerpo 422 incluye un array errors de nivel superior con mensajes legibles por humanos, junto a la lista detail en bruto.

La referencia completa de códigos de estado está en la guía de códigos de error.

Límites#

Preguntas frecuentes#

¿Cómo convierto una página web a Markdown con una API REST?#

Envía POST /v2/perceive con {"url": "...", "outputs": ["markdown"]}. La página se renderiza en Chrome headless y la respuesta lleva una URL de descarga pre-firmada para el archivo Markdown. Por defecto, only_main_content elimina el chrome del sitio para que recibas el artículo, no la navegación; define "only_main_content": false para la página completa, o añade "direct_download": true para recibir los bytes del Markdown directamente en el cuerpo de la respuesta.

¿Puedo obtener una captura de pantalla y Markdown del mismo render?#

Sí. outputs acepta cualquier combinación, así que ["markdown", "screenshot"] (o screenshot_full_page para todo el alto del scroll) produce ambos a partir de un único render de navegador. Nunca pagas por la misma página dos veces en una llamada.

¿/v2/perceive renderiza páginas JavaScript?#

Sí. Cada solicitud ejecuta un render real en Chrome headless: se descartan los banners de cookies, se hace scroll en la página para disparar el contenido de carga diferida, y puedes controlar la página antes de la captura con wait_for (un selector CSS o una expresión JS), js_code, y block_resources.

¿Por qué dejó de funcionar mi URL de descarga firmada?#

Las URLs firmadas expiran a los 15 minutos (expires_in: 900). Vuelve a obtener la operación con GET /v2/perceive/{operation_id} para conseguir URLs recién firmadas. No se produce ningún re-render y no se consumen ops.

¿Un resultado en caché sigue contando contra mi cuota?#

Sí. Un acierto de caché factura una op, porque la cuota mensual mide operaciones, no renders de navegador. Define cache_mode como bypass para omitir la caché de 1 hora, o refresh para renderizar de nuevo y reemplazar la entrada en caché.