V1 y V2: convertir archivos o leer la web#
La API de EnConvert tiene dos mitades. V1 (/v1/convert/...) convierte un archivo o una URL al formato que indiques; V2 (/v2/...) lee una página web en vivo y devuelve datos que un agente puede usar. Una sola clave cubre las dos mitades en una misma URL base, y ambas facturan contra el mismo contador.
La regla de decisión#
Si ya sabes qué formato de salida quieres, eso es V1. Si lo que quieres es saber qué hay en una página, eso es V2.
| Qué estás haciendo | Mitad | Empieza aquí |
|---|---|---|
| Convertir esta URL en un PDF | V1 | url-to-pdf |
| Convertir este DOCX en un PDF | V1 | Documentos |
| Convertir este JSON en YAML | V1 | Formatos de datos |
| Convertir este HEIC en un WebP | V1 | Imágenes |
| Leer esta página como Markdown para un LLM | V2 | Perceive |
| Obtener Markdown, una captura de pantalla, enlaces y metadatos de un solo renderizado | V2 | Perceive |
| Convertir un sitio entero en fragmentos para RAG | V2 | Ingest |
El borde incómodo: url-to-markdown (V1) y perceive (V2) se solapan. Usa V1 cuando quieras un archivo Markdown y nada más. Usa V2 cuando además quieras la captura de pantalla, los enlaces, los metadatos de la página o la opción de recibir los bytes inline.
V1: conversión determinista#
Envías bytes o una URL, y el endpoint al que llamas es el formato de destino. POST /v1/convert/png-to-webp devuelve WebP. Nada decide nada por ti.
Hay 49 endpoints de conversión de destino único repartidos en cuatro familias, más dos rastreadores de sitios web que recorren un sitio entero y devuelven un ZIP, así que 51 rutas en total.
| Familia | Endpoints | Entrada |
|---|---|---|
| Páginas web | 5 | Una URL (o una lista de URLs) en un cuerpo JSON |
| Documentos | 13 | Una subida de archivo (multipart/form-data) |
| Formatos de datos | 11 | Una subida de archivo (multipart/form-data) |
| Imágenes | 22 | Una subida de archivo (multipart/form-data) |
De esos, website-to-pdf y website-to-screenshot son los dos rastreadores: descubren páginas bajo un dominio y siempre responden de forma asíncrona con 202 y un ZIP. Todos los demás endpoints convierten una entrada en una salida. El mapa completo de entrada a salida está en la matriz de conversión.
Una llamada a V1 tiene este aspecto:
curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
-H "X-API-Key: sk_your_private_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/pricing"}'
{
"presigned_url": "https://spaces.example.com/...signed...",
"object_key": "env/files/{project_id}/url-to-pdf/example_20260404_123456789.pdf",
"filename": "example_20260404_123456789.pdf",
"file_size": 123456,
"conversion_time_seconds": 12.5
}
Establece direct_download=true en una solicitud síncrona de una sola URL y el cuerpo de la respuesta será el propio PDF en lugar de ese JSON.
V2: leer la web en vivo#
V2 renderiza una página en Chrome headless real (con JavaScript ejecutado y contenido lazy cargado) y devuelve lo que hay en ella: Markdown, HTML limpio o en bruto, una captura de pantalla, un PDF, el inventario de enlaces e imágenes, datos estructurados de la página o fragmentos listos para RAG. Más que indicar un formato de salida, indicas qué salidas quieres de un único renderizado.
Esta es la llamada útil más pequeña. Envía una URL a /v2/perceive 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_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 Markdown y el bloque estructurado inline:
{
"operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
"status": "completed",
"url_final": "https://example.com/pricing",
"render_quality": 0.93,
"outputs": {
"markdown": {
"url": "https://spaces.example.com/...signed...",
"size_bytes": 8421,
"expires_in": 900
}
},
"structured": {
"metadata": {"title": "Pricing"}
}
}
Envías JSON y recibes un resultado inline o una URL firmada de corta duración a un artefacto. Esa es la forma de todos los endpoints de V2.
Qué está disponible hoy#
Se pueden llamar los seis endpoints de V2. Dos de ellos tienen disponibilidad general: Perceive e Ingest.
| Endpoint | Estado | Qué hace |
|---|---|---|
POST /v2/perceive |
Disponible | Renderiza una URL una vez y devuelve cada salida que pidas: Markdown, HTML limpio o en bruto, captura de pantalla, PDF, enlaces, imágenes y datos estructurados. |
POST /v2/ingest |
Disponible | Rastrea un sitio (o acepta archivos subidos) y emite un único archivo JSONL de fragmentos listos para RAG, de forma asíncrona detrás de un job_id. |
| Distill | Beta privada | Referencia |
| Lookup | Beta privada | Referencia |
| Watch | Beta privada | Referencia |
| Discover | Beta privada | Referencia |
Qué comparten las dos mitades#
V2 es puramente aditivo. Los endpoints de V1 no cambian y no se ven afectados por nada de esto. No hay migración: añades V2 junto a V1 cuando lo necesitas.
Una sola clave. Una clave privada sk_ en la cabecera X-API-Key, o una clave pública pk_ intercambiada por un token JWT bearer, funciona igual en V1 y en V2. Consulta la guía de autenticación para conocer el flujo completo, incluidos el bloqueo de dominio y la renovación de tokens.
Una sola lista de permitidos. Cada clave de API lleva una lista de endpoints permitidos. Una ruta de V2 que no está en la lista de la clave se rechaza con 403, igual que ocurriría con una ruta de V1.
Un solo contador. Las conversiones V1 y las operaciones V2 facturan el mismo contador mensual de ops. Una op es una unidad de trabajo: una conversión, una URL percibida, una página ingerida. No hay multiplicadores por endpoint, así que un renderizado caro cuesta la misma op que una conversión de JSON a YAML. Las cuotas de cada plan están en límites de frecuencia y cuotas.
Un solo mecanismo de entrega. La salida de archivos de cualquiera de las dos mitades se sube al almacenamiento y se devuelve como una URL prefirmada que expira a los 15 minutos (expires_in: 900). Vuelve a consultar la operación, el trabajo o el lote para generar un conjunto nuevo; volver a firmar no vuelve a renderizar nada y no cuesta ops. Los detalles están en URLs firmadas.
Decisiones de diseño que valen para todo V2#
Apréndelas una vez y se aplican a todo V2.
Un solo renderizado a través de un navegador compartido. Perceive e Ingest renderizan a través del mismo singleton de Chrome headless y el mismo pipeline de captura que hay detrás de el endpoint url-to-pdf de V1. Los banners de cookies se descartan, la página se desplaza para activar el contenido lazy, y a las imágenes se les da tiempo para cargar.
Protección SSRF en cada URL. Antes de cualquier fetch o renderizado, se revisan en cada URL el esquema, las credenciales incrustadas, los hostnames bloqueados y la IP resuelta. Una URL que resuelve a una dirección privada, loopback, link-local o de metadatos de nube se rechaza con 400. Esto se aplica por igual a las seeds y a los enlaces rastreados.
Puntuación de calidad de renderizado. Cada renderizado lleva una puntuación render_quality de 0.0 a 1.0. Una puntuación baja señala una página que parece bloqueada por protección anti-bot u oculta detrás de un muro de login, para que puedas distinguir una captura real de una página de challenge.
Credenciales solo donde son seguras. Perceive acepta auth, cookies y headers personalizados para páginas detrás de un login. Ingest deliberadamente no lo hace, porque sus trabajos son duraderos y reanudables y no debe persistirse nada secreto para una reanudación. ¿Necesitas credenciales para una página dentro de un set de ingest? Renderízala en su lugar a través de perceive.
Los parámetros reservados lo dicen. Cuando un parámetro es aceptado por el esquema pero todavía no está conectado, V2 te lo dice en lugar de ignorarlo en silencio. Los proxy_url, geolocation y action_chain de perceive devuelven 422 hoy en día; sus nombres de extracción prices, contacts y technologies caen en warnings y se descartan.
warnings en cada respuesta, y espera que los cuerpos de respuesta ganen campos antes de que V2 salga de beta. Pueden aparecer campos nuevos; los ya documentados no cambiarán de significado en silencio.
Por dónde empezar#
- Convertir un archivo o una URL: los endpoints de Convert.
- Leer una página: el endpoint perceive.
- Construir un corpus para RAG a partir de un sitio: el endpoint ingest.
- Probar los endpoints en beta privada: Próximamente.
Si todavía no has hecho tu primera llamada, la guía de inicio rápido te explica paso a paso cómo obtener una clave y ejecutar una request de principio a fin.
Preguntas frecuentes#
¿Necesito una clave de API aparte para V2?#
No. Una sola clave cubre las dos mitades. Una clave privada sk_ en la cabecera X-API-Key, o un JWT generado a partir de una clave pública pk_, autentica igual en V1 y en V2, sujeta a la lista de endpoints permitidos de la clave.
¿V2 reemplaza a V1?#
No. V2 es aditivo y V1 no cambia. Si quieres un formato de salida concreto a partir de un archivo o una URL, V1 sigue siendo la llamada correcta, y así se queda.
¿Cómo se cuenta el uso entre V1 y V2?#
Las dos mitades facturan un único contador mensual de ops, y una op es una unidad de trabajo: una conversión V1, una URL percibida, una página ingerida. No hay ponderación por endpoint. Consulta límites de frecuencia y cuotas.
¿Qué endpoints de V2 puedo llamar hoy?#
Los seis. Perceive e Ingest tienen disponibilidad general. Distill, Lookup, Watch y Discover están en beta privada: se pueden llamar con tu clave habitual, están documentados en Próximamente, pueden cambiar de forma sin avisar, y Watch además necesita un plan de pago.