Visão geral

hotdoc é uma API de processamento de documentos. Você envia arquivos e instruções de texto (prompts) e recebe de volta o texto reconhecido e as respostas do modelo para cada arquivo.

Por baixo dos panos, o hotdoc faz três coisas: descompacta arquivos compactados e normaliza seus arquivos, passa-os por OCR e então envia o texto reconhecido a um modelo de linguagem junto com seus prompts. Você não precisa subir nenhuma infraestrutura, não configura um pipeline de OCR e não paga markup sobre tokens — o modelo roda com a sua chave de provedor (BYOK).

O processamento é assíncrono. Você cria um job, recebe seu ID e consulta o status até o job terminar. Um único job pode conter vários arquivos, inclusive arquivos aninhados dentro de arquivos compactados.

O hotdoc é uma boa escolha quando:

• você precisa transformar um conjunto variado de documentos (PDFs, scans, arquivos do Office, arquivos compactados) em texto e extrair dados deles via API;
• você não quer manter sua própria infraestrutura de reconhecimento;
• você não quer pagar tokens caros por meio de um intermediário — você paga o provedor do modelo diretamente.

O que o hotdoc não faz: ele não converte um formato de arquivo em outro como um fim em si mesmo (não é um conversor) e não garante uma saída válida em relação a um schema (veja “Prompts e extração de dados”).

Como a API funciona em 1 minuto

Uma única URL base (https://api.hotdoc.io), um cabeçalho de autenticação, processamento assíncrono: você cria um job, recebe seu id e consulta o status até o job terminar.

Os métodos se dividem em três grupos (lista completa com os caminhos em “Referência da API”):

O fluxo principal tem três passos:

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[])

Não há um endpoint separado de logs: os dados e erros por estágio (OCR/LLM) ficam em /result; a lista de jobs é GET /v1/jobs; a cota restante é GET /v1/billing.

Conceitos principais

Job. A unidade de processamento. Contém um ou mais arquivos de origem, passa pelos estágios de processamento e tem um status. Há limites para o tamanho total de um job (veja “Limites”). No plano gratuito, o uso é contado em jobs.

Source. Um arquivo a ser processado. Você o especifica como uma URL pública em sourceUrls ou enviando-o primeiro (veja “Envio de arquivos”). Se um source for um arquivo compactado, ele é descompactado recursivamente (profundidade padrão ≤ 3) e cada arquivo aninhado é processado separadamente.

Estágios de processamento. Cada arquivo passa por: descompactação/conversão → OCR (reconhecimento de texto) → LLM (envio do texto ao modelo com seus prompts).

Prompt. Uma instrução de texto para o modelo. Você passa um array prompts; o modelo o aplica ao texto reconhecido de cada arquivo e retorna uma resposta em texto.

BYOK / neural. A configuração do modelo cuja chave é usada no estágio de LLM. É passada no campo neural ao criar um job. A chave do provedor nunca é armazenada em texto plano — somente criptografada — e é excluída junto com o job (veja “Segurança e dados”).

BYOK / ocr. A configuração do provedor de OCR no qual o estágio de reconhecimento (OCR) é executado. É passada no campo ocr ao criar um job e é sempre obrigatória, ao lado de neural. Você escolhe o provedor via ocr.provider (por exemplo, NEURAL_CLIENT_TYPE_MISTRAL), o modelo via ocr.model (por exemplo, mistral-ocr-latest) e fornece sua chave em ocr.providerKey. É uma chave separada de neural.apiKey: neural.apiKey é a chave do provedor do modelo de linguagem (estágio de LLM), enquanto ocr.providerKey é a chave do provedor de OCR para reconhecimento de texto (estágio de OCR). O conversor decide por conta própria se um determinado arquivo precisa de OCR; para arquivos de texto puro a chave pode não ser usada, mas você precisa enviá-la de qualquer forma. A chave é armazenada apenas criptografada, nunca é retornada nas respostas e é excluída junto com o job.