Ejecutar en el sandbox

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.

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.

Convert#

51 endpoints de conversión, todos con la forma POST /v1/convert/<id>, 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.

En desarrollo#

Distill, Lookup, Watch y Discover están en beta privada y no se cubren aquí. Se describen en Próximamente, 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 <token>`, 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.

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.
`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 y Webhooks.
`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í:

{
    "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:

{
    "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.

Errores#

Los fallos vuelven como un objeto JSON con un campo detail:

{
    "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. Los límites de plan que disparan 402, 413 y 429 están en Límites de frecuencia y cuotas.

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. Las rutas de configuración y de token de los widgets viven bajo /v1/widget/ y se cubren en Integraciones.

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.

← V1 and V2 Perceive →

API Documentation