Inicio rápido de la API de Ingest

Sube un archivo e inicia un trabajo de ingesta en tres llamadas HTTP.

21 may 2026

La API de Ingest convierte un archivo sin procesar (PDF, imagen, audio, texto) en un documento buscable en tu Biblioteca de Vulgate. Es un proceso de dos pasos: subir el archivo, luego iniciar un trabajo de ingesta.

La referencia completa está en /developers/ingest/overview. Esta guía recorre lo mínimo necesario para subir tu primer archivo desde código.

Paso 1 — Solicitar una URL de subida firmada

Vulgate usa URLs de almacenamiento firmadas para que las subidas de archivos eviten el servidor API por completo. Primero, solicita una URL de /api/uploads:

curl -G "https://vulgate.ai/api/uploads" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "name=articulo-investigacion.pdf" \
  --data-urlencode "type=application/pdf"

Respuesta:

{
  "url": "https://...url-almacenamiento-firmada...",
  "method": "PUT",
  "headers": {
    "content-type": "application/pdf",
    "x-amz-meta-name": "articulo-investigacion.pdf"
  }
}

Guarda el ID del archivo devuelto en los headers (x-amz-meta-name junto con la parte de ruta de la URL) — lo necesitarás en el paso 3. La URL firmada es válida por un período corto.

Paso 2 — Subir el archivo a la URL firmada

Envía el cuerpo del archivo como un PUT a la URL firmada con los headers del paso 1. No incluyas el header de autenticación de Vulgate aquí — la firma maneja la autenticación:

curl -X PUT "<url-firmada-del-paso-1>" \
  -H "Content-Type: application/pdf" \
  -H "X-Amz-Meta-Name: articulo-investigacion.pdf" \
  --data-binary @articulo-investigacion.pdf

El servicio de almacenamiento responde con HTTP 200 y sin cuerpo cuando es exitoso.

Paso 3 — Iniciar un trabajo de ingesta

Dile a Vulgate que comience a procesar el archivo subido haciendo POST a /api/jobs con el ID del archivo del paso 1:

curl -X POST "https://vulgate.ai/api/jobs" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [{ "id": "<id-archivo-del-paso-1>" }],
    "ingest_mode": "standard"
  }'

ingest_mode selecciona el nivel de procesamiento: "standard" (el predeterminado — OCR rápido, 1 crédito/página, todos los tipos de archivo) o "pro" (extracción con modelo de visión para escaneos difíciles, 5 créditos/página, solo PDF e imágenes). Consulta la referencia completa de parámetros para las demás opciones — pipeline, alcance, metadatos del documento y procesamiento de audio.

El trabajo se ejecuta en segundo plano. Una vez que se complete, el documento es buscable — llama a la API de Search o API de Chat para interactuar con él.

Subidas multiparte para archivos grandes

El flujo de archivo único anterior funciona bien para archivos típicos. Para archivos muy grandes, usa los endpoints multiparte (POST /api/uploads). Consulta Subir archivos para la referencia completa.

Relacionado

Buscar ayuda