Быстрый старт

От API-ключа до первого структурированного ответа /v1/process — управляетесь за 5 минут.

1. Получите API-ключ

Ключ выпускается самостоятельно: введите почту на странице входа в кабинет, перейдите по одноразовой ссылке из письма — первый ключ выдается сразу при первом входе. Значение ключа показывается один раз, в момент выдачи.

100 страниц бесплатно — без карты и без выбора тарифа;
ключ выглядит как docai_sk_... и передается в заголовке X-API-Key на каждый запрос — подробнее в разделе «Аутентификация»;
дальше — тарифы «Старт»/«Про» или доплата за перерасход, тоже без остановки потока (см. «Аутентификация» → «Квоты и биллинг»).

Если код писать не нужно

Тот же движок работает в кабинете мышкой: раздел «Обработка документов» — тип документа, колонки, файл, Excel с переводом. Годится и как быстрая проверка «а справится ли сервис с моим документом» до интеграции — см. «Кабинет и обработка без кода».

Дальше в этом разделе $API_KEY — переменная окружения с вашим ключом:

export API_KEY="docai_sk_..."

2. Первый запрос — задача словами по готовому тексту

Самый быстрый способ получить ответ — прислать текст, а не файл: OCR не нужен, тело запроса — обычный JSON. Задачу описываете в prompt, форму ответа — в output_schema:

curl -X POST https://api.docinspect.ru/v1/process \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Договор поставки № 118-СТ от 12.03.2026 между ООО «Балтмонтаж» (поставщик) и ООО «Невский Провиант» (покупатель)...",
    "prompt": "Определи категорию документа: договор, акт, счет или УПД.",
    "output_schema": {
      "type": "object",
      "properties": {
        "category": { "type": "string" },
        "reason": { "type": "string", "description": "по каким признакам определена категория" }
      }
    }
  }'

Ответ приходит синхронно — и всегда в одном и том же конверте:

{
  "result": { "category": "договор", "reason": "есть предмет, стороны и срок действия" },
  "documents": null,
  "markdown": null,
  "fragments": null,
  "tables": null,
  "fields": null,
  "match": null,
  "usage": { "pages": 1, "sheets": null },
  "metadata": { "file_hash": null, "extraction_status": "full", "input_quality_score": null, "cached": false },
  "warnings": []
}

Секции, которые вы не заказывали, приходят null, а не отсутствуют — код на типизированном клиенте не должен проверять наличие ключа. result повторяет форму, заданную в output_schema, — это и есть контракт, который стоит проектировать в первую очередь: см. «output_schema».

Промпт без схемы не существует

prompt без непустой output_schema — ошибка PROMPT_REQUIRES_SCHEMA (422). Если нужен текстовый ответ, опишите его схемой из одного поля: {"type":"object","properties":{"summary":{"type":"string"}}}. result всегда JSON-объект.

3. Второй запрос — с файлом

Реальный сценарий почти всегда начинается с файла. Тот же эндпоинт, то же множество полей — меняется только тип тела: multipart/form-data, а объекты (output_schema, include, split, match) передаются JSON-строками в form-полях.

curl -X POST https://api.docinspect.ru/v1/process \
  -H "X-API-Key: $API_KEY" \
  -F "file=@invoice.pdf" \
  -F "prompt=Извлеки реквизиты сторон, позиции и итоговую сумму счета" \
  -F 'output_schema={"type":"object","properties":{
        "supplier":{"type":"object"},
        "customer":{"type":"object"},
        "items":{"type":"array"},
        "total_amount":{"type":"number"}}}'

Файл — до 50 МБ (413 FILE_TOO_LARGE), список форматов — в «Форматах и лимитах». Если документ не на русском и не на английском, добавьте -F "language=zh": без подсказки языка китайский скан распознается плохо. Перевод значений и выгрузка в Excel — там же, в «/v1/process».

Если поля из потока однотипных документов всегда одни и те же, промпт можно опустить — останется output_schema, и сервис сам разберется, где искать поля. Это чуть быстрее и подходит для конвейерных сценариев; на нестандартных документах и смысловых вопросах промпт работает лучше.

4. Длинный документ — асинхронно

Внешний прокси обрывает соединение на 300 секундах, а OCR+LLM большого скана занимают минуты. Для таких документов добавьте async: true — ответ придет сразу, с идентификатором задачи:

curl -X POST https://api.docinspect.ru/v1/process \
  -H "X-API-Key: $API_KEY" \
  -F "file=@lease_scan.pdf" \
  -F "async=true" \
  -F "prompt=Извлеки особые условия аренды: каникулы, эксклюзивность, индексация" \
  -F 'output_schema={"type":"object","properties":{"special_conditions":{"type":"array","items":{"type":"object"}}}}'

{ "task_id": "be4b0d…", "poll_url": "/v1/process/be4b0d…" }

Результат забирается тем же ключом:

curl https://api.docinspect.ru/v1/process/be4b0d… -H "X-API-Key: $API_KEY"

{ "task_id": "be4b0d…", "status": "done", "result": { "result": { "…": "…" }, "usage": { "pages": 91, "sheets": 91 } }, "error": null }

status — processing | done | error; результат живет 1 час. Подробности — «/v1/process» → Асинхронный режим.

Что дальше

/v1/process — полный контракт: все поля запроса, конверт ответа, разбиение, сверка с реестром, цитирование по страницам;
output_schema — как спроектировать схему ответа так, чтобы модель не путалась (самая частая причина плохих результатов у новичков);
Форматы и лимиты — что можно прислать на вход и в каких границах по размеру;
Готовые сценарии — копируемый код под реальные сценарии: ЭДО, чертежи, приемка поставки, разбор архива договоров;
Ошибки — что делать с 422, частичным результатом и warnings[].