API para Extraer Datos Estructurados de un Sitio Web#

POST /v2/distill es una API para extraer datos estructurados de sitios web: extrae campos de una o más URLs para que coincidan con un esquema que tú proporcionas, ya sea un objeto JSON-Schema o un mapa plano {field: description}. Ejecuta un motor de dos pasadas: primero una pasada CSS gratuita (JsonCssExtractionStrategy de Crawl4AI, controlada por tus selectores), y luego una pasada limitada asistida por LLM para los campos que la pasada CSS dejó vacíos. La respuesta data está garantizada a devolverse exactamente en la forma que pediste. Será la respuesta de EnConvert a /extract de Firecrawl.

Aquí tienes la llamada útil más pequeña. Envía una URL y un esquema plano {field: description}, y recibe de vuelta los campos extraídos:

curl -X POST https://api.enconvert.com/v2/distill \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/product/widget"],
    "schema": {
      "name": "the product name",
      "price": "the listed price",
      "in_stock": "whether it is in stock"
    }
  }'

La respuesta trae un resultado por URL, los data extraídos, y qué nivel los produjo:

{
    "operation_id": "dst_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "total": 1,
    "completed": 1,
    "failed": 0,
    "results": [
        {
            "url": "https://example.com/product/widget",
            "url_final": "https://example.com/product/widget",
            "status": "completed",
            "data": {
                "name": "Widget Pro",
                "price": "$49.00",
                "in_stock": "yes"
            },
            "extraction_tier": "llm",
            "fields_from_css": 0,
            "fields_from_llm": 3,
            "render_quality": 0.91,
            "tokens": {"input": 4120, "output": 38},
            "cost_cents": 0.45,
            "warnings": []
        }
    ],
    "total_cost_cents": 0.45,
    "warnings": []
}

Endpoints#

Content-Type: application/json.

A diferencia de perceive, distill es un único endpoint síncrono: no hay una ruta separada de reobtención GET ni un camino asíncrono por lotes. Cada URL se renderiza secuencialmente a través del singleton compartido de Chrome headless y el conjunto completo de resultados vuelve en una sola respuesta.

Autenticación#

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

X-API-Key: sk_your_private_key

Las claves públicas con un token bearer JWT 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, incluyendo el bloqueo de dominio y la renovación de tokens, está en la guía de autenticación.

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

Cómo funciona distill#

Una solicitud aplica distill a una lista de URLs contra un esquema. El flujo es el mismo para cada URL:

1. Resuelve la lista de URLs. Con urls, la lista es exactamente lo que enviaste (deduplicada, con el orden preservado). Con discover_from, distill ejecuta discover primero sobre la URL semilla (analizando el sitemap, rastreando, o ambas cosas) y luego aplica distill a las URLs descubiertas hasta max_pages.
2. Renderiza. Cada URL se renderiza una vez en Chrome headless a través del mismo pipeline de captura que impulsa perceive. El renderizado se filtra contra SSRF y, si respect_robots=true, se verifica contra el robots.txt del sitio. No se sube ningún artefacto al almacenamiento, porque distill solo necesita el DOM renderizado.
3. Pasada 1: CSS (gratis). Si proporcionaste un css_schema, el extractor CSS se ejecuta sobre el HTML renderizado y llena cada campo direccionable por selector a costo cero de LLM. Esta pasada está limitada a 10 segundos; si se agota el tiempo, la URL cae a la pasada LLM con una advertencia.
4. Pasada 2: LLM (limitada, solo cuando hace falta). Distill recopila los campos del esquema que la pasada CSS dejó faltantes o vacíos y escala solo esos campos a una pasada asistida por LLM, bajo topes de presupuesto estrictos por llamada y por período. Si tu plan no tiene nivel LLM, la página fue marcada como bloqueada, o se alcanza un tope de presupuesto, la pasada LLM se omite y los campos faltantes vuelven como null con una advertencia.
5. Normaliza. El resultado combinado se remodela para que coincida exactamente con las claves de tu esquema: los escalares faltantes se vuelven null, los arrays faltantes se vuelven [], y cualquier clave extra se descarta. La garantía de forma se mantiene sin importar lo que haya producido CSS o el LLM.

Se factura una op por URL, y solo después de que esa URL se completa. Los fallos de renderizado (rechazo por SSRF, bloqueo de robots, un renderizado fallido) producen una fila de resultado failed y no cuestan ops.

Parámetros de la solicitud#

Debes proporcionar exactamente uno de urls o discover_from, más un schema. Enviar ambos, o ninguno, produce un 422.

Origen: URLs explícitas#

Origen: descubrir y luego aplicar distill#

Esquema o prompt#

Proporciona o bien un schema (la forma de salida que quieres) o bien un prompt (una descripción en lenguaje natural de qué extraer). Se requiere exactamente uno; si envías ambos, gana schema.

El esquema es el contrato. Si envías un objeto JSON-Schema, distill lee sus properties; si envías un mapa plano, cada clave nombra un campo y cada valor es la descripción que se le pasa al LLM. De cualquier forma, data vuelve con exactamente las claves de nivel superior del esquema.

Modo solo-prompt. Si envías un prompt en lugar de un schema, distill primero sintetiza un esquema de campos a partir de tu prompt, y luego extrae contra él. Los campos sintetizados se devuelven como eco en la respuesta como synthesized_schema. El modo solo-prompt usa el nivel de extracción LLM y requiere un plan que lo incluya; sin uno, distill devuelve una advertencia clara en lugar de adivinar.

Esquema CSS (opcional)#

Proporciona un css_schema para responder campos gratis antes de cualquier llamada al LLM. Sin él, todos los campos caen directo a la pasada LLM.

Cada entrada en fields es un CssField:

Vale la pena señalar: el tipo de campo computed de Crawl4AI deliberadamente no se acepta. Su forma de expresión ejecuta eval sobre la entrada del llamador, y su forma invocable no puede cruzar un límite JSON, así que distill enumera solo los siete tipos seguros de arriba.

Controles de renderizado#

Distill solo renderiza el DOM, así que expone un pequeño subconjunto de las opciones de renderizado de perceive.

Respuesta#

POST /v2/distill devuelve un DistillResponse:

Cada entrada en results es un DistillItemResult:

Para ser directos: la respuesta no lleva URLs de descarga firmadas ni artefactos almacenados. Distill devuelve la data estructurada en línea y nada más. Si además quieres el Markdown de la página, el HTML, una captura de pantalla, o un PDF, para eso está perceive.

El modelo de costo de dos pasadas#

La pasada CSS es gratis. La pasada LLM cuesta dinero, así que distill la dispara lo más acotada posible y la limita desde varios frentes.

Escala solo los campos faltantes. Después de la pasada CSS, distill calcula qué campos del esquema siguen vacíos: un escalar que volvió como null/"", un array que volvió vacío, o un array cuyos elementos carecen de un sub-campo declarado. Solo esos nombres de campo entran en un esquema reducido para la llamada al LLM, lo que mantiene el prompt y el costo al mínimo.

Omite la pasada LLM por completo cuando se cumple cualquiera de estas condiciones, devolviendo el resultado solo-CSS con una advertencia en lugar de sobregastar:

• Tu plan no tiene nivel LLM (llm_extraction_enabled más un agent_model_tier distinto de none).
• El render_quality de la página la marcó como bloqueada por protección anti-bot.
• Se alcanza el presupuesto de LLM por solicitud para esta llamada, o se alcanza el tope de presupuesto por período.

Los topes de presupuesto están en capas:

Nota. El presupuesto por período se reserva de forma atómica antes de la llamada y se ajusta al costo real después, así que las llamadas concurrentes no pueden superar el tope en conjunto. Un proyecto sin una fila de período de uso activa falla de forma segura, porque el gasto que EnConvert no puede contabilizar es gasto que no realiza. Cuando se alcanza un tope, los campos afectados vuelven como null con una advertencia; la solicitud igual se completa con éxito.

Cuando la pasada LLM sí se ejecuta, extraction_tier reporta llm o mixed, y tokens y cost_cents reportan lo que costó. Cuando no se ejecuta, ambos son cero.

Cómo se mapean los registros de CSS a tu esquema#

El caso común es una página de listado: una fila repetida, y un esquema de salida con una propiedad de tipo array para contener las filas. Dale a distill un css_schema cuyo baseSelector coincida con la fila y cuyos fields lean las columnas, y llenará el array gratis:

curl -X POST https://api.enconvert.com/v2/distill \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/products"],
    "schema": {
      "type": "object",
      "properties": {
        "products": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {"type": "string"},
              "price": {"type": "string"},
              "sku": {"type": "string"}
            }
          }
        }
      }
    },
    "css_schema": {
      "baseSelector": ".product-card",
      "target_field": "products",
      "fields": [
        {"name": "name", "type": "text", "selector": ".title"},
        {"name": "price", "type": "text", "selector": ".price"},
        {"name": "sku", "type": "attribute",
         "selector": ".product-card", "attribute": "data-sku"}
      ]
    }
  }'

Cómo aterrizan los registros en el esquema:

• target_field establecido en una propiedad de tipo array → esa propiedad recibe la lista completa de registros.
• target_field establecido en una propiedad escalar/objeto → recibe el primer registro.
• target_field omitido, el esquema tiene exactamente una propiedad de tipo array → distill lo infiere y llena esa propiedad.
• De lo contrario → el primer registro se trata como un único objeto plano y sus claves coincidentes se elevan al nivel superior.

Si CSS llena el array pero algunos elementos carecen de un sub-campo declarado (digamos que sku falta en la mitad de las tarjetas), distill escala products a la pasada LLM para llenar los vacíos. Ese es el diferenciador de dos pasadas frente a un scraper plano: estructurado donde se pueda, respaldado por modelo donde haga falta.

Ejemplos de código#

curl: esquema plano, solo LLM#

curl -X POST https://api.enconvert.com/v2/distill \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/article"],
    "schema": {
      "headline": "the article headline",
      "author": "the author name",
      "published": "the publish date"
    }
  }'

curl: descubrir y luego aplicar distill#

curl -X POST https://api.enconvert.com/v2/distill \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "discover_from": {
      "url": "https://example.com/blog",
      "mode": "sitemap",
      "max_pages": 25
    },
    "schema": {
      "title": "the post title",
      "summary": "a one-line summary"
    }
  }'

Python#

import requests

response = requests.post(
    "https://api.enconvert.com/v2/distill",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "urls": ["https://example.com/product/widget"],
        "schema": {
            "name": "the product name",
            "price": "the listed price",
            "in_stock": "whether it is in stock",
        },
    },
)
response.raise_for_status()
result = response.json()

for item in result["results"]:
    if item["status"] == "completed":
        print(item["url"], "->", item["data"])
    else:
        print(item["url"], "FAILED:", item["error"])

print("total cost (cents):", result["total_cost_cents"])

Node.js#

const res = await fetch("https://api.enconvert.com/v2/distill", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_your_private_key"
    },
    body: JSON.stringify({
        urls: ["https://example.com/product/widget"],
        schema: {
            name: "the product name",
            price: "the listed price",
            in_stock: "whether it is in stock"
        }
    })
});

const result = await res.json();

for (const item of result.results) {
    if (item.status === "completed") {
        console.log(item.url, "->", item.data);
    } else {
        console.log(item.url, "FAILED:", item.error);
    }
}

console.log("total cost (cents):", result.total_cost_cents);

Respuestas de error#

Algunas notas de estado que vale la pena tener claras: una sola URL cuyo renderizado es rechazado por SSRF muestra un 400 solo cuando es la semilla de una solicitud discover_from; para una lista explícita de urls, un rechazo de renderizado por URL se convierte en una fila de resultado failed en lugar de hacer fallar toda la solicitud. Un tope de presupuesto de LLM nunca es un error, porque se degrada a un resultado solo-CSS con una advertencia. La referencia completa de códigos de estado está en la guía de códigos de error.

Límites#

Preguntas frecuentes#

¿Cómo extraigo datos estructurados de un sitio web con una API REST?#

Envía POST /v2/distill con urls (hasta 50 por solicitud) y un schema, ya sea un objeto JSON-Schema o un mapa plano {field: description}. La data de la respuesta vuelve normalizada a exactamente las claves de nivel superior de tu esquema.

¿Puedo extraer un sitio web hacia un esquema JSON sin escribir selectores CSS?#

Sí. css_schema es opcional, y sin él todos los campos caen directo a la pasada asistida por LLM. Proporcionar un css_schema llena gratis los campos direccionables por selector y escala solo los campos que la pasada CSS dejó vacíos.

¿Cuánto cuesta la pasada de extracción LLM, y cómo se limita?#

Los topes de presupuesto están en capas: $0.05 por llamada al LLM, $0.50 por solicitud a /v2/distill, como máximo 50 escalaciones por solicitud, y por período tu saldo mensual de créditos de IA ($5 / $15 / $40 en Indie / Studio / Production; los créditos no usados se acumulan). La extracción con LLM consume créditos, no ops. Alcanzar un tope nunca hace fallar la solicitud: los campos afectados vuelven como null con una advertencia.

¿Por qué algunos campos aparecen como null en mi respuesta de distill?#

Los escalares faltantes se normalizan a null (y los arrays faltantes a []) para preservar la garantía de forma. La pasada LLM se omite (con una advertencia) cuando tu plan no tiene nivel LLM, el render_quality de la página la marcó como bloqueada, o se alcanzó un tope de presupuesto.

¿Puedo rastrear un sitio completo y extraer el mismo esquema de cada página?#

Sí. Envía discover_from con una url semilla, un mode (sitemap, crawl, o hybrid), y max_pages (1–50) en lugar de urls. Requiere el flag de plan discover_enabled; sin él la solicitud se rechaza con 402.