Обзор
hotdoc — это API для обработки документов. Вы отправляете файлы и текстовые инструкции (промпты), а в ответ получаете распознанный текст и ответы модели по каждому файлу.
Под капотом hotdoc делает три вещи: распаковывает архивы и приводит файлы к единому виду, прогоняет их через OCR, а затем отправляет распознанный текст в языковую модель с вашими промптами. Вы не поднимаете инфраструктуру, не настраиваете OCR-пайплайн и не платите наценку за токены — модель работает на вашем ключе провайдера (BYOK).
Обработка асинхронная. Вы создаёте задачу (job), получаете её идентификатор и опрашиваете статус, пока задача не завершится. Один job может содержать несколько файлов, в том числе вложенных в архивы.
Когда подходит hotdoc:
- нужно превратить разнородные документы (PDF, сканы, Office-файлы, архивы) в текст и извлечь из них данные через API;
- не хотите держать собственную инфраструктуру распознавания;
- не хотите переплачивать за токены через посредника — платите провайдеру модели напрямую.
Что hotdoc не делает: не конвертирует один формат файла в другой как самоцель (это не конвертер), не возвращает гарантированно валидную структуру по схеме (см. «Промпты и извлечение данных»).
Как работает API за 1 минуту
Один базовый URL (https://api.hotdoc.io), один заголовок авторизации, асинхронная обработка: вы создаёте задачу, получаете id и опрашиваете статус, пока задача не завершится.
Методы сгруппированы в три набора (полный перечень с путями — в «Справочнике API»):
| Набор | Методов | Зачем |
|---|---|---|
| Обработка (Jobs) | 5 | создать задачу, статус, результат, список задач, загрузка файла |
| Аккаунт и ключи | 6 | профиль, переименование аккаунта, участники, создать/список/отозвать API-ключ |
| Биллинг | 4 | статус квоты, тарифы, оформление и портал подписки |
Ядро работы — три шага:
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[])Отдельного эндпоинта логов нет: данные и ошибки по стадиям (OCR/LLM) лежат в /result; список задач — GET /v1/jobs; остаток квоты — GET /v1/billing.
Основные понятия
Задача (job). Единица обработки. Содержит один или несколько источников-файлов, проходит через стадии обработки и имеет статус. На задачу действуют лимиты по суммарному размеру (см. «Лимиты»). Free-тариф считается в задачах.
Источник (source). Файл, который нужно обработать. Задаётся либо публичной ссылкой в sourceUrls, либо предварительной загрузкой (см. «Загрузка файлов»). Если источник — архив, он распаковывается рекурсивно (глубина по умолчанию ≤ 3), и каждый вложенный файл обрабатывается отдельно.
Стадии обработки. Каждый файл проходит: распаковку/конвертацию → OCR (распознавание текста) → LLM (отправка текста в модель с вашими промптами).
Промпт (prompt). Текстовая инструкция модели. Вы передаёте массив prompts; модель применяет их к распознанному тексту каждого файла и возвращает текстовый ответ.
BYOK / neural. Конфигурация модели, на ключе которой выполняется LLM-стадия. Передаётся в поле neural при создании задачи. Ключ провайдера не хранится в открытом виде — только в зашифрованном, и удаляется вместе с задачей (см. «Безопасность и данные»).
BYOK / ocr. Конфигурация OCR-провайдера, на котором выполняется стадия распознавания (OCR). Передаётся в поле ocr при создании задачи и обязательна всегда, наравне с neural. Провайдер задаётся через ocr.provider (например, NEURAL_CLIENT_TYPE_MISTRAL), модель — через ocr.model (например, mistral-ocr-latest), ключ — через ocr.providerKey. Это отдельный ключ от neural.apiKey: neural.apiKey — ключ провайдера языковой модели (LLM-стадия), ocr.providerKey — ключ OCR-провайдера для распознавания текста (OCR-стадия). Конвертер сам решает, нужен ли OCR конкретному файлу; для чисто текстовых файлов ключ может не использоваться, но прислать его нужно в любом случае. Ключ хранится только в зашифрованном виде, в ответах не возвращается и удаляется вместе с задачей.