Perceive

POST /v2/perceive renderiza una URL una sola vez en un navegador real y devuelve todas las salidas que solicites a partir de ese único renderizado: Markdown, HTML limpio o crudo, 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). Reemplaza un conjunto de llamadas separadas — url-to-markdown, url-to-screenshot, url-to-pdf, además de tu propio scraping — con una sola solicitud.

Aquí tienes la llamada útil más pequeña. Envía una URL y recibe Markdown limpio y los metadatos estructurados de la página:

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

La respuesta incluye una URL de descarga prefirmada para el archivo Markdown y el bloque estructurado en línea:

{
    "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": "Pro", "offers": {"price": "99"}}
        ]
    },
    "extraction_tier": "heuristic",
    "tokens": {"input": 0, "output": 0},
    "cost_cents": 0.0,
    "duration_ms": 6230,
    "warnings": []
}

Conviene señalarlo de entrada. /v2/perceive es un endpoint V2 con su propio contador de cuota. Los planes de conversión V1 no incluyen ninguna operación perceive de V2 — necesitas un plan que incluya V2 para llamarlo. Consulta la página de precios para ver las asignaciones por nivel.

Endpoints

Content-Type: application/json en cada POST.

Authentication

Autentícate con una clave privada en el encabezado X-API-Key para llamadas servidor a servidor. Esta es la vía que usan los ejemplos de abajo.

X-API-Key: sk_live_your_private_key

Las claves públicas con un token bearer JWT también funcionan, usando el mismo flujo que todos los demás endpoints — genera un token con tu clave pk_ y luego envíalo como Authorization: Bearer <token>. El flujo completo, incluyendo el bloqueo de dominio y la renovación del token, está en la guía de autenticación.

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

How perceive works

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

1. Renderizar. La página se carga en Chrome headless. Se descartan los banners de cookies, se desplaza la página para activar el contenido de carga diferida, se gestionan los encabezados fijos y se da tiempo a que las imágenes carguen — el mismo pipeline de captura que impulsa el endpoint url-to-pdf.
2. Materializar. A partir del DOM renderizado, perceive construye lo que hayas listado en outputs: Markdown, HTML limpio/crudo, enlaces, imágenes, una captura de pantalla, un PDF.
3. Extraer. Si solicitaste la salida structured, perceive ejecuta una pasada heurística para los metadatos de la página, JSON-LD, encabezados y tablas. Si además envías un schema y tu plan incluye el nivel LLM, un modelo Anthropic Claude Haiku rellena el esquema cuando la pasada heurística se queda corta.
4. Puntuar. Una puntuación de calidad del renderizado (0.0–1.0) marca las páginas que parecen bloqueadas por protección anti-bot u ocultas tras un muro de inicio de sesión, para que puedas distinguir un renderizado real de una página de desafío.

Las salidas binarias 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 prefirmadas que expiran tras 15 minutos. El bloque structured se devuelve en línea en el JSON. Vuelve a obtener cualquier operación con GET /v2/perceive/{operation_id} para conseguir un nuevo conjunto de URLs firmadas.

Request parameters

Core

Outputs

outputs acepta cualquier combinación de estos nombres:

Rendering and waiting

Authenticated and custom requests

Structured extraction

Cuando structured está en outputs, la lista extract controla qué campos extrae perceive. No pidas nada y por defecto será metadata y structured_data.

Para ser claros: prices, contacts y technologies son nombres reservados. Solicita uno hoy y no da error — aterriza en el array warnings y se descarta de structured.

Schema-driven extraction

Envía un schema para extraer campos específicos a 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 LLM (Anthropic Claude Haiku) rellena el esquema, y solo se dispara cuando se cumplen todas estas condiciones: enviaste un schema, tu plan incluye el nivel LLM (Starter en adelante), la página no se puntuó como bloqueada y la pasada heurística dejó vacíos los campos del esquema. Cuando se ejecuta, extraction_tier es "llm", y tokens y cost_cents informan de lo que costó esa extracción; en caso contrario extraction_tier es "heuristic" y ambos son cero.

Nota. La extracción por esquema tiene un tope estricto para proteger tu factura: una sola extracción está limitada por solicitud, y el gasto diario por proyecto está limitado por el plan. Si se alcanza un tope, 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.

Response

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

Retrieve an operation

Las URLs firmadas expiran tras 15 minutos. Para descargar una salida más tarde, vuelve a obtener la operación — perceive vuelve a firmar cada URL a partir de las claves de objeto almacenadas. No ocurre ningún re-renderizado, así que esto no consume cuota.

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

Un ID de operación desconocido, o uno que pertenece a un proyecto distinto, devuelve 404 — la existencia nunca se filtra entre proyectos.

Batch perception

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 produce su propia fila de operación.

curl -X POST https://api.enconvert.com/v2/perceive/batch \
  -H "X-API-Key: sk_live_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 en línea y responden 200 con cada resultado poblado. Los lotes más grandes responden 202 con un job_id; las URLs se drenan de una en una y consultas los resultados:

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

La respuesta del lote informa del progreso agregado y lleva un resultado perceive completo por 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 o partial (algunas URLs tuvieron éxito, otras fallaron). Establece output_mode en zip para agrupar todos los artefactos en un único ZIP, devuelto bajo el campo zip una vez que el lote termina. El acceso a lotes y el tamaño máximo de lote están limitados por plan; consulta la página de precios.

Caching

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

Conviene señalarlo: un acierto de caché sigue contando como una operación perceive contra tu cuota mensual. La cuota mide operaciones, no renderizados del navegador — la caché te ahorra tiempo de renderizado, no cuota.

Code examples

curl — Markdown only

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

curl — Markdown plus structured data

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

curl — Full outputs plus PDF

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_live_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_live_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_live_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.

Plan gating

Las operaciones perceive de V2 son un contador separado de las conversiones de V1. Los planes V1 no incluyen cuota de perceive; necesitas un plan que incluya V2.

El acceso a lotes y los límites de tamaño por lote, el soporte de basic-auth/cookie/header y proxy_url (Business+, cuando se lance) están limitados por plan. Las cifras actuales están en la página de precios.

Error responses

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

Limits