--- seo_title: Endpoints de la API: Perceive, Ingest y Convert | EnConvert meta_desc: Todos los endpoints de EnConvert en un lugar: Perceive para leer una página, Ingest para rastrear un sitio y 51 rutas de Convert, más el contrato común. keywords: endpoints api enconvert, lista de endpoints de la api, cabecera x-api-key, url base de la api, subida multipart form data, respuesta con url prefirmada, parámetros de solicitud api, endpoint de health check, contrato de solicitud api --- # Endpoints de la API de EnConvert EnConvert tiene tres grupos de endpoints. Perceive lee una página web, Ingest rastrea un sitio entero y lo convierte en fragmentos, y Convert transforma archivos y URLs a otros formatos. Comparten una URL base, una clave de API y una única cuota mensual de ops, así que el contrato de solicitud que viene más abajo aplica a los tres. --- ## Perceive `POST /v2/perceive` renderiza una URL una vez en un navegador headless y devuelve todo lo que hayas pedido a partir de ese único renderizado: Markdown, HTML limpio o en bruto, una captura de pantalla, un PDF, el inventario de enlaces e imágenes y los datos estructurados de la página. Cinco rutas en total, incluido un endpoint por lotes que acepta una lista de URLs bajo un mismo conjunto de opciones, limitada por el límite de lote de tu plan. Consulta [Perceive](/es/docs/endpoints/perceive.md). ## Ingest `POST /v2/ingest` rastrea un sitio y escribe todas sus páginas en un único archivo JSONL de fragmentos listos para RAG; `POST /v2/ingest/files` hace lo mismo con los documentos que subes. Ingest siempre es asíncrono: el POST responde `202` con un `job_id`, y a partir de ahí lo sondeas o recibes un webhook firmado. Ocho rutas, incluidas la rotación del secreto del webhook y el reenvío manual. Consulta [Ingest](/es/docs/endpoints/ingest.md). ## Convert 51 endpoints de conversión, todos con la forma `POST /v1/convert/`, agrupados en cuatro familias: páginas web, documentos, formatos de datos e imágenes. Cada uno recibe una subida de archivo o una URL y escribe el resultado en el almacenamiento. Consulta [Convert](/es/docs/endpoints/convert.md). ## En desarrollo Distill, Lookup, Watch y Discover están en beta privada y no se cubren aquí. Se describen en [Próximamente](/es/docs/coming-soon.md), junto con la fase a la que pertenece cada uno. --- ## Parámetros de solicitud compartidos Todo lo de esta sección vale para los tres grupos. Lo específico de una conversión concreta está en la página de ese endpoint. ### URL base ``` https://api.enconvert.com ``` Todas las rutas de esta página son relativas a ese host. El gateway mantiene una solicitud abierta durante 300 segundos como máximo; si para entonces no ha empezado a llegar una respuesta, obtienes `504` con `{"error": "Request timeout"}`. ### Autenticación Cada solicitud lleva uno de los dos encabezados de credenciales. El token Bearer se lee primero y la clave de API después. Si no envías ninguno, la API responde `401` con `Authentication required`. | Encabezado | Obligatorio | Descripción | |--------|----------|-------------| | `X-API-Key` | Uno de los dos | Tu clave de API. Las claves privadas empiezan por `sk_` y las públicas por `pk_`. | | `Authorization` | Uno de los dos | `Bearer `, donde el token es un JWT generado a partir de una clave pública en `POST /v1/auth/token`. Los tokens de acceso duran una hora. | | `Content-Type` | Sí | `application/json` para cuerpos JSON, `multipart/form-data` para subidas de archivos. | | `X-Parent-Origin` | Solo widgets | El dominio principal que incrusta el widget; obligatorio para el intercambio de tokens con clave pública. |
Las claves privadas son solo de servidor. Cualquier solicitud que lleve un encabezado Origin presentando una clave sk_ se rechaza con 403 Private API keys cannot be used from browsers. En código de cliente, intercambia una clave pública por un JWT.
El modelo completo de claves, incluidas las listas de dominios permitidos y los ámbitos de endpoints por clave, está en [Autenticación](/es/docs/authentication.md). ### Tipos de contenido Hay dos formas de solicitud. **Cuerpo JSON (`application/json`)** - Todos los endpoints `/v2` salvo `POST /v2/ingest/files`. - Los cinco endpoints de conversión de páginas web. Su campo `url` acepta una cadena con una URL o un array de cadenas de URL. **Formulario multipart (`multipart/form-data`)** - Los 46 endpoints de conversión de archivos, que leen la subida desde un campo `file`. - `POST /v2/ingest/files`, que lee una lista de subidas desde un campo `files`. Las subidas se comprueban por la extensión del nombre de archivo y por un sniff de los primeros bytes (magic bytes). Una discrepancia de alta confianza, como un archivo llamado `.pdf` cuyos bytes son un PNG, devuelve `400`. Los formatos de texto como JSON, CSV, XML, YAML, TOML, Markdown, HTML y SVG no llevan firma de bytes, así que pasan el sniff y fallan más adelante en el conversor si el contenido está mal formado. ### Parámetros comunes | Parámetro | Se aplica a | Qué hace | |-----------|------------|--------------| | `output_filename` | Endpoints de conversión V1 | Nombra el archivo de salida. Siempre se añade una marca de tiempo UTC: `{output_filename}_{YYYYMMDD_HHMMSSmmm}.{ext}`. Si incluyes la extensión de destino, se elimina antes, así que nunca acabas con una extensión duplicada. | | `direct_download` | Todos los endpoints V1 de conversión, `POST /v2/perceive` | Devuelve los bytes del artefacto como cuerpo de la respuesta en lugar de un envoltorio JSON. El valor por defecto cambia según el endpoint: `true` en las subidas de archivos y `false` en los endpoints de URL con clave privada. Consulta [URLs firmadas](/es/docs/concepts/signed-urls.md). | | `async_mode`, `callback_url`, `notification_email` | Endpoints V1 de URL | Ponen el trabajo en cola en lugar de esperar a que termine, y te avisan cuando acaba. Consulta [Trabajos síncronos y asíncronos](/es/docs/concepts/sync-and-async.md) y [Webhooks](/es/docs/guides/webhooks.md). | | `pdf_options` | Endpoints que producen PDF | Tamaño de página, márgenes, orientación, escala, encabezado y pie de página, escala de grises. La lista de campos está en la página de cada endpoint de PDF. | Nombres de salida predeterminados cuando no pasas `output_filename`: - **Subidas de archivos:** derivado del nombre del archivo de entrada, así que `report.docx` se convierte en `report_20260405_123456789.pdf`. - **Conversiones de URL:** derivado del nombre de dominio, así que `example_20260405_123456789.pdf`. - **Alternativa:** `output_20260405_123456789.{ext}`. ### Envoltorio de respuesta Una conversión V1 síncrona responde `200` con la ubicación del archivo, no con el archivo en sí: ```json { "presigned_url": "https://spaces.example.com/...signed...", "object_key": "live/files/4127/url-to-pdf/example_20260405_123456789.pdf", "filename": "example_20260405_123456789.pdf", "file_size": 48213, "conversion_time_seconds": 2.41 } ``` Las respuestas de conversión repiten esos metadatos en encabezados: | Encabezado | Descripción | |--------|-------------| | `Content-Disposition` | `inline; filename="{filename}"` | | `X-Object-Key` | Ruta de almacenamiento del archivo convertido | | `X-File-Size` | Tamaño del archivo convertido en bytes | | `X-Conversion-Time` | Tiempo que tomó la conversión, en segundos | | `X-Filename` | Nombre de archivo generado | Los endpoints V2 devuelven sus propios envoltorios JSON, documentados en sus páginas, pero cada artefacto almacenado dentro de esos envoltorios usa una única forma: ```json { "url": "https://spaces.example.com/...signed...", "object_key": "live/files/4127/v2-perceive/per_3f9a..._markdown.md", "size_bytes": 8421, "content_type": "text/markdown; charset=utf-8", "expires_in": 900 } ```
Las URLs firmadas duran 15 minutos. Funcionan más de una vez dentro de esa ventana, y volver a sondear el endpoint de estado de un trabajo genera una URL nueva sobre el mismo objeto. Descarga el archivo o cópialo a tu propio almacenamiento sin demora.
Más sobre expiración, reutilización y retención: [URLs firmadas](/es/docs/concepts/signed-urls.md). ### Errores Los fallos vuelven como un objeto JSON con un campo `detail`: ```json { "detail": "Monthly operations limit reached (500/500). Upgrade your plan to continue." } ``` `413 Payload Too Large` es la excepción: su `detail` es un objeto con `error`, `file_size`, `max_size`, `tier` y `key_type`. Los códigos de estado y los mensajes que hay detrás están en [Errores](/es/docs/reference/errors.md). Los límites de plan que disparan `402`, `413` y `429` están en [Límites de frecuencia y cuotas](/es/docs/reference/rate-limits.md). --- ## Endpoints de servicio | Endpoint | Método | Descripción | |----------|--------|-------------| | `/health` | `GET` | Comprobación de estado. Devuelve `200` cuando la base de datos, el almacenamiento y el navegador responden, y `503` cuando alguno no lo hace. Sin autenticación. | | `/v1/whoami` | `GET` | Devuelve `{"project_id": ..., "plan_slug": ...}` para la clave privada que presentas. Una clave pública o un JWT reciben `403`. | La generación, renovación y verificación de tokens viven bajo `/v1/auth/` y se cubren en [Autenticación](/es/docs/authentication.md). Las rutas de configuración y de token de los widgets viven bajo `/v1/widget/` y se cubren en [Integraciones](/es/docs/guides/integrations.md). ## Preguntas frecuentes ### ¿Qué endpoints aceptan subida de archivos? Los 46 endpoints de conversión de archivos y `POST /v2/ingest/files`. Leen `multipart/form-data`. Todo lo demás acepta un cuerpo JSON, incluidos los cinco endpoints de conversión de páginas web, que aceptan una cadena `url` o un array de URLs. ### ¿Los endpoints V2 usan la misma clave de API que los endpoints de conversión? Sí. Una clave, un proyecto, una cuota mensual. Cada unidad de trabajo cuesta una op, ya sea una conversión de archivo, una URL percibida o una página ingerida. No hay contadores por endpoint ni multiplicadores de créditos. ### ¿Cómo compruebo si la API está operativa? Llama a `GET /health`. Devuelve `200` cuando la base de datos, el almacenamiento y el navegador responden, y `503` cuando alguno no lo hace; no requiere autenticación. ### ¿Cuánto tiempo siguen siendo válidas las URLs de descarga? 15 minutos. Una URL puede usarse varias veces antes de expirar, y volver a sondear el endpoint de estado de un trabajo devuelve una URL recién firmada para el mismo archivo. ### ¿Por qué una conversión devuelve una URL en lugar del archivo? Por dos razones. Una conversión grande puede tardar de 60 a 120 segundos, tiempo suficiente para que un proxy inverso delante de tu código abandone una respuesta en streaming, y el mismo resultado a menudo hay que descargarlo más de una vez. Así que los bytes van al almacenamiento y tú recibes una URL firmada hacia ellos. Cuando te conviene más un solo viaje de ida y vuelta, `direct_download` devuelve los bytes inline.