Visión general

hotdoc es una API de procesamiento de documentos. Envía archivos e instrucciones de texto (prompts) y recibe de vuelta el texto reconocido y las respuestas del modelo para cada archivo.

Internamente, hotdoc hace tres cosas: descomprime archivos comprimidos y normaliza sus archivos, los pasa por OCR y luego envía el texto reconocido a un modelo de lenguaje junto con sus prompts. No tiene que montar ninguna infraestructura, no configura un pipeline de OCR y no paga ningún recargo sobre los tokens: el modelo se ejecuta con la clave de su proveedor (BYOK).

El procesamiento es asíncrono. Crea una tarea, obtiene su ID y consulta su estado hasta que la tarea termina. Una sola tarea puede contener varios archivos, incluidos los anidados dentro de archivos comprimidos.

hotdoc encaja bien cuando:

• necesita convertir una mezcla de documentos (PDF, escaneos, archivos de Office, comprimidos) en texto y extraer datos de ellos vía API;
• no quiere operar su propia infraestructura de reconocimiento;
• no quiere pagar de más por los tokens a través de un intermediario: paga directamente al proveedor del modelo.

Lo que hotdoc no hace: no convierte un formato de archivo a otro como fin en sí mismo (no es un conversor) y no garantiza una salida válida según un esquema (consulte «Prompts y extracción de datos»).

Cómo funciona la API en 1 minuto

Una sola URL base (https://api.hotdoc.io), una cabecera de autenticación y procesamiento asíncrono: crea una tarea, obtiene su id y consulta el estado hasta que la tarea termina.

Los métodos se agrupan en tres bloques (lista completa con rutas en «Referencia de la API»):

El flujo principal son tres pasos:

POST /v1/jobs            → create a job (status JOB_STATUS_NEW)
GET  /v1/jobs/{id}       → poll the status (NEW → FILE_PROCESSING → OCR → LLM → terminal)
GET  /v1/jobs/{id}/result → fetch the result: recognized text (ocr[]) and model answers (llm[])

No hay un endpoint de logs aparte: los datos y errores por etapa (OCR/LLM) viven en /result; la lista de tareas es GET /v1/jobs; la cuota restante es GET /v1/billing.

Conceptos básicos

Job (tarea). La unidad de procesamiento. Contiene uno o más archivos de origen, avanza por las etapas de procesamiento y tiene un estado. Los límites se aplican al tamaño total de una tarea (consulte «Límites»). En el plan gratuito, el uso se cuenta en tareas.

Source (origen). Un archivo que se va a procesar. Lo indica como una URL pública en sourceUrls o subiéndolo primero (consulte «Subida de archivos»). Si un origen es un archivo comprimido, se descomprime de forma recursiva (profundidad por defecto ≤ 3) y cada archivo anidado se procesa por separado.

Etapas de procesamiento. Cada archivo pasa por: descompresión/conversión → OCR (reconocimiento de texto) → LLM (envío del texto al modelo con sus prompts).

Prompt. Una instrucción de texto para el modelo. Pasa un array prompts; el modelo lo aplica al texto reconocido de cada archivo y devuelve una respuesta de texto.

BYOK / neural. La configuración del modelo con cuya clave se ejecuta la etapa LLM. Se pasa en el campo neural al crear una tarea. La clave del proveedor nunca se almacena en texto plano —solo cifrada— y se elimina junto con la tarea (consulte «Seguridad y datos»).

BYOK / ocr. La configuración del proveedor de OCR con el que se ejecuta la etapa de reconocimiento (OCR). Se pasa en el campo ocr al crear una tarea y es siempre obligatoria, junto con neural. Elige el proveedor mediante ocr.provider (p. ej. NEURAL_CLIENT_TYPE_MISTRAL), el modelo mediante ocr.model (p. ej. mistral-ocr-latest) y aporta su clave en ocr.providerKey. Es una clave distinta de neural.apiKey: neural.apiKey es la clave del proveedor del modelo de lenguaje (etapa LLM), mientras que ocr.providerKey es la clave del proveedor de OCR para el reconocimiento de texto (etapa OCR). El conversor decide por sí mismo si un archivo concreto necesita OCR; para archivos de texto plano la clave puede quedar sin usar, pero debe enviarla de todos modos. La clave se almacena solo cifrada, nunca se devuelve en las respuestas y se elimina junto con la tarea.