--- seo_title: V1 y V2: convertir archivos o leer la web | EnConvert meta_desc: V1 convierte archivos y URLs entre formatos. V2 lee la web en vivo para agentes y pipelines de RAG. Cuál llamar en cada caso y qué llega después. keywords: v1 vs v2 api, api de conversión de archivos vs scraping, las dos mitades de la api de enconvert, api de datos web para agentes de ia, api url a markdown, api de ingesta para rag, qué endpoint de la api usar, una clave de api dos apis --- # 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.
Disponible hoy: todo V1, más los seis endpoints de V2. Perceive e Ingest tienen disponibilidad general. Distill, Lookup, Watch y Discover se pueden llamar, pero están en beta privada, documentados en Próximamente, y sus formas pueden cambiar sin avisar.
--- ## 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](/es/docs/endpoints/convert/web-pages/url-to-pdf.md) | | Convertir este DOCX en un PDF | V1 | [Documentos](/es/docs/endpoints/convert/documents.md) | | Convertir este JSON en YAML | V1 | [Formatos de datos](/es/docs/endpoints/convert/data-formats.md) | | Convertir este HEIC en un WebP | V1 | [Imágenes](/es/docs/endpoints/convert/images.md) | | Leer esta página como Markdown para un LLM | V2 | [Perceive](/es/docs/endpoints/perceive.md) | | Obtener Markdown, una captura de pantalla, enlaces y metadatos de un solo renderizado | V2 | [Perceive](/es/docs/endpoints/perceive.md) | | Convertir un sitio entero en fragmentos para RAG | V2 | [Ingest](/es/docs/endpoints/ingest.md) | 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](/es/docs/endpoints/convert/web-pages.md) | 5 | Una URL (o una lista de URLs) en un cuerpo JSON | | [Documentos](/es/docs/endpoints/convert/documents.md) | 13 | Una subida de archivo (`multipart/form-data`) | | [Formatos de datos](/es/docs/endpoints/convert/data-formats.md) | 11 | Una subida de archivo (`multipart/form-data`) | | [Imágenes](/es/docs/endpoints/convert/images.md) | 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](/es/docs/concepts/sync-and-async.md) 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](/es/docs/endpoints/convert/matrix.md). Una llamada a V1 tiene este aspecto: ```bash 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"}' ``` ```json { "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: ```bash 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: ```json { "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`](/es/docs/endpoints/perceive.md) | 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`](/es/docs/endpoints/ingest.md) | 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](/es/docs/coming-soon/distill.md) | | Lookup | Beta privada | [Referencia](/es/docs/coming-soon/lookup.md) | | Watch | Beta privada | [Referencia](/es/docs/coming-soon/watch.md) | | Discover | Beta privada | [Referencia](/es/docs/coming-soon/discover.md) |
Las cuatro últimas filas son beta privada. Distill, Lookup, Watch y Discover responden a solicitudes reales hoy, pero no están anunciados, no tienen disponibilidad general y sus formas de solicitud y respuesta pueden cambiar sin avisar, así que mantenlos fuera de cualquier cosa crítica. Watch necesita un plan de pago; los otros tres funcionan en cualquier plan, Founding incluido. Los detalles están en Próximamente.
--- ## 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](/es/docs/authentication.md) 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](/es/docs/reference/rate-limits.md). **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](/es/docs/concepts/signed-urls.md). --- ## 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](/es/docs/endpoints/convert/web-pages/url-to-pdf.md). 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](/es/docs/endpoints/perceive.md). **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.
V2 está en beta. Fija tu integración a los nombres de campo y códigos de estado documentados, lee 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](/es/docs/endpoints/convert.md). - **Leer una página:** [el endpoint perceive](/es/docs/endpoints/perceive.md). - **Construir un corpus para RAG a partir de un sitio:** [el endpoint ingest](/es/docs/endpoints/ingest.md). - **Probar los endpoints en beta privada:** [Próximamente](/es/docs/coming-soon.md). Si todavía no has hecho tu primera llamada, [la guía de inicio rápido](/es/docs/quickstart.md) 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](/es/docs/reference/rate-limits.md). ### ¿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](/es/docs/coming-soon.md), pueden cambiar de forma sin avisar, y Watch además necesita un plan de pago.