API — Resumen

Este playground expone POST /api/analyze como fachada didáctica sobre src/lib/docmind-server.ts, que delega en @dragon708/docmind-node y, para acciones solo PDF o solo DOCX, en helpers de @dragon708/docmind-pdf y @dragon708/docmind-docx. El OCR raster y TIFF multipágina pueden usar @dragon708/docmind-ocr mediante el campo JSON options y las acciones siguientes.

No es una API de producto lista para producción (sin versionado ni API keys en este ejemplo).
Refleja las acciones de Server test, Client test (SDK en navegador, incl. extractStructuredData), PDF lab (/[locale]/pdf-lab), DOCX lab (/[locale]/docx-lab) y OCR lab (/[locale]/ocr-lab).
Desplegar esta ruta en Vercel (u otro Next.js serverless) exige outputFileTracingIncludes / serverExternalPackages para PDF.js y Tesseract—véase Instalación.

Petición

Método / URL: POST /api/analyze
Content-Type: multipart/form-data

Campos del formulario

Campo	Obligatorio	Descripción
`file`	Sí	Fichero subido (`File` en `FormData`).
`action`	No (por defecto `analyze`)	Ver Acciones.
`ocrMode`	Sí*	`off` \| `auto` \| `force`. Se mapea a `pdf.ocr` (y lógica del playground) donde aplique—ver Modo OCR. *La ruta lo valida siempre; envía un valor aunque la acción lo ignore.
`language`	No	Cadena recortada: `ocr.langs`, `pdf.ocrLangs` y `langs` del pipeline. No aplica a `detect-kind` ni `capabilities`.
`maxPages`	No	Entero positivo: tope de páginas PDF desde la 1 donde la ruta lo use (`analyze`, `extract-text`, `convert-html`, `extract-structured`, acciones PDF.js por página, acciones DOCX que reenvían `maxPages`, …). Vacío = sin tope.
`ocrStrategy`	No	Pipeline OCR PDF: `native-first`, `ocr-only` o `hybrid`, o vacío para el valor por defecto del SDK. Se usa cuando corre OCR (`analyze`, `extract-text`, `convert-html`, `extract-structured`, `pdf-extract-text-by-page`, `pdf-extract-pages` con `ocrMode` ≠ `off`).
`planIntent`	No	Para `explain-plan`: `analyzeFile` \| `extractText` \| `extractMetadata` \| `convertToHtml` \| `runOcr` \| `extractStructuredData`.
`formValues`	No	Objeto JSON solo para `pdf-fill-form` (nombre de campo → string \| boolean \| string[]). Objeto vacío si no aplica.
`docxInclude_structure`, `docxInclude_headings`, …	No	Valor `1` / `true` / `on` activa esa clave en `options.docx.include` en `analyze`, `extract-text`, `convert-html`, `ocr`, `explain-plan`, `extract-structured` y `docx-analyze`. Ver `src/lib/docxInclude.ts`.
`options`	No	Cadena JSON (objeto) para `@dragon708/docmind-ocr` en acciones raster (sección siguiente) y para `extract-structured` (rama imagen: `preprocess` opcional hacia `extractStructuredData`). Campos: `langs`, `preprocess`, `debug`, TIFF `maxPages` / `pageSeparator`, `mimeHint`, y (para `action=ocr`) `implementation: "pkg"` (o `engine: "docmind-ocr"` / `source: "pkg"`) para usar `ocr()` del paquete en lugar de `runOcr` de Node. Omitido o vacío = `{}`. JSON inválido → 400.

Acciones

Núcleo (router / facetas)

`action`	Wrapper	Notas
`analyze`	`analyzeServerFile`	`analyzeFile` completo + `NodeAnalyzeOptions`.
`detect-kind`	`detectServerFileKind`	`{ fileKind }`.
`extract-text`	`extractServerText`	`ocrMode` → `pdf.ocr` (PDF escaneados: `auto` / `force`; en Node, `extractText` fuerza PDF OCR `off` si no pasas `pdf.ocr`).
`extract-metadata`	`extractServerMetadata`	El playground puede completar número de páginas con `getPdfPageCount` si el stub de metadatos PDF seguía en `pages: 0`.
`convert-html`	`convertServerToHtml`	Mismos `ocrMode` / idioma / `maxPages` / `ocrStrategy` que `analyze` para PDF.
`ocr`	`runServerOcr` o `serverOcrRaster`	Por defecto: `runOcr` de Node (PDF forzado + imagen). Si `options` marca OCR del paquete (`implementation: "pkg"`, o `engine: "docmind-ocr"`, o `source: "pkg"`), llama a `ocr()` de `@dragon708/docmind-ocr` vía `serverOcrRaster`.
`capabilities`	`getServerCapabilities`
`explain-plan`	`explainServerAnalysisPlan`	Opcional `planIntent`.
`extract-structured`	`extractServerStructuredData`	Cualquier `fileKind`: `extractStructuredData` en Node con `pdf.ocr` / `maxPages` / `ocrStrategy` del formulario, `docx.include` opcional desde *`docxInclude_`, imagen: `ocr.langs` y `options.preprocess` desde `language` / `options`. Forma JSON: `StructuredDocumentResult`**.

Solo PDF (`@dragon708/docmind-pdf`)

Exige fileKind === "pdf" (si no, 400).

`action`	Helper	Función
`pdf-extract-text-by-page`	`serverPdfExtractTextByPage`	Texto por página. Con `ocrMode`: `off` = solo capa PDF.js; `auto` = pipeline `native-first`; `force` = estrategia `ocrStrategy` (por defecto `ocr-only`).
`pdf-extract-pages`	`serverPdfExtractPages`	Mismo OCR + metadatos de viewport por página.
`extract-pdf-by-page`	(alias)	Igual que `pdf-extract-text-by-page`.
`pdf-outline`	`serverPdfOutline`
`pdf-links`	`serverPdfLinks`
`pdf-annotations`	`serverPdfAnnotations`
`pdf-form-fields`	`serverPdfFormFields`
`pdf-fill-form`	`serverPdfFillForm`	Requiere `formValues` JSON.
`pdf-flatten-form`	`serverPdfFlattenForm`

Solo DOCX

Exige fileKind === "docx" (si no, 400).

`action`	Comportamiento
`docx-analyze`	`analyzeServerFile` + casillas *`docxInclude_`**.
`docx-extract-text`	`extractServerText` + includes DOCX.
`docx-convert-html`	`convertServerToHtml` + includes + idioma.
`docx-structure`	Analyze con `include.structure`.
`docx-headings`	`include.headings`.
`docx-blocks`	`include.blocks`.
`docx-tables`	`include.tables`.
`docx-pages-approx`	`include.pagesApprox`.
`docx-images-raw` \| `docx-images-web` \| `docx-images-both`	`serverExtractImagesFromDocx` con `mode`.

Cruce de formatos: extract-structured también está en las UIs de DOCX lab y PDF lab (mismo valor de action); conviene subir el tipo de archivo acorde para un resultado útil.

Acciones OCR raster (`@dragon708/docmind-ocr`)

Entrada: bytes de imagen raster o TIFF. El playground usa language como ocr.langs si options.langs va vacío. OCR lab construye options.

`action`	Helper	Función
`ocr` (con `options` pkg)	`serverOcrRaster`	Fachada `ocr()`: rasters de una página + enrutado TIFF multipágina.
`ocr-detailed`	`serverOcrImageDetailed`	Bloques/líneas, tiempos, `options.preprocess` opcional.
`ocr-tiff`	`serverOcrTiff`	Solo TIFF multipágina; `options.maxPages`, `options.pageSeparator`.
`normalize-only`	`serverNormalizeImageForOcr`	Metadatos de normalización; `options.debug.returnNormalized: true` incluye PNG en base64 en JSON.
`preprocess-only`	`serverPreprocessImageForOcr`	Metadatos de preprocess; `options.debug.returnPreprocessed: true` para PNG base64.

options.preprocess (cuando aplica): grayscale, threshold (0–255), resize: { width?, height?, fit? }, normalize. Ver tipos del paquete PreprocessImageOptions.

Modo OCR según acción

Usa `ocrMode` → `pdf.ocr` (o equivalente)	Papel
`analyze`, `explain-plan`, `extract-text`, `convert-html`, `extract-structured`	Misma política que en el SDK con `pdf: { ocr, ocrLangs?, … }`.
`pdf-extract-text-by-page`, `pdf-extract-pages`	`off`: solo texto nativo PDF.js. `auto`: `runPdfOcrPipeline` con `native-first`. `force`: pipeline según `ocrStrategy`.
Acciones DOCX basadas en analyze	Se reenvía `sharedPdfOpts`; en un DOCX puro no afecta el PDF.
`detect-kind`, `capabilities`, `extract-metadata`, `ocr` (rama Node), estructura PDF sin OCR	`ocrMode` sigue siendo obligatorio en el formulario; la acción puede ignorarlo.
`ocr` (rama pkg), `ocr-detailed`, `ocr-tiff`, `normalize-only`, `preprocess-only`	`ocrMode` flexible: valores inválidos o vacíos se tratan como `auto` (sin 400).

JSON de éxito y binarios DOCX

En respuestas correctas, result pasa por sanitizeDocxBinaryForJson: en imágenes embebidas DOCX se eliminan data / Uint8Array del JSON (sustituidos por dataByteLength) para no inflar la respuesta como { "0": …, "1": … }. Se mantienen cadenas base64 para vistas previas o clientes. Es específico del playground; usa el SDK en proceso si necesitas bytes crudos.

Respuesta de error


{
  "success": false,
  "action": "analyze",
  "result": null,
  "error": "Mensaje legible",
  "code": "codigo_docmind_opcional"
}

Si el valor lanzado es DocMindError, se rellena code. Otros fallos pueden devolver HTTP 500 con mensaje genérico.

Ejemplo (`curl`)


curl -s -X POST "http://localhost:3000/api/analyze" \
  -F "action=analyze" \
  -F "ocrMode=auto" \
  -F "language=eng" \
  -F "file=@./muestra.pdf"

(Ajusta origen y ruta a tu servidor de desarrollo.)

Ver también

Referencia API (interactiva) — cada método por paquete + ejemplos en la app
Guía Node
Guía OCR — modos PDF, idioma en navegador, paquete raster y options
PDF lab, DOCX lab y OCR lab desde la home de la app (/[locale]).