Форматы и лимиты
Что можно прислать в /v1/process — PDF, офисные форматы, изображения, XML — и в каких границах по размеру.
Что принимает вход
POST /v1/process принимает один источник: либо файл, либо готовый
текст в поле text (markdown или plain text — тогда OCR и разбор не нужны).
| Группа | Расширения | Особенности |
|---|---|---|
.pdf | Единственный формат, где доступны split, tables и fields | |
| Офисные документы | .doc, .docx | Текстовый слой читается напрямую |
| Таблицы | .xls, .xlsx, .csv | Также принимаются как registry для сверки |
| Изображения | .jpg, .jpeg, .png, .tiff, .tif, .webp | Фото и сканы идут через OCR |
| XML | .xml | Двухэтажная поддержка, см. ниже |
Расширение вне списка — 422 UNSUPPORTED_FILE_TYPE; в details.supported
приходит актуальный список, так что зашивать его в свой код не обязательно.
Почему секции fields и tables только для PDF
tables — таблицы, собранные по линиям сетки векторного слоя, fields —
provenance: страница и координаты, где найдено значение. И то и другое
существует, только когда у документа есть геометрия страницы. На тексте,
XML и таблице эти секции приходят null с предупреждением
section_unavailable, даже если запрошены через include.
XML — два этажа
XML разбирается безопасным парсером: внешние сущности и entity-бомбы (XXE, «billion laughs») отклоняются, а не выполняются.
Generic-этаж — любой well-formed XML. Документ превращается в markdown:
элементы становятся структурой, атрибуты — парами «ключ — значение»,
повторяющиеся узлы не теряются. Дальше он неотличим от любого другого
документа: схема, промпт и fragments работают без изменений.
Маппинг-этаж — известные форматы без модели. Для форматов из каталога
маппингов (корневой элемент + namespace → XPath полей) значения читаются
детерминированно. Если маппинг закрывает всю запрошенную output_schema,
LLM не вызывается вовсе:
curl -X POST https://api.docinspect.ru/v1/process \
-H "X-API-Key: $API_KEY" \
-F "file=@invoice.xml" \
-F 'output_schema={"type":"object","properties":{
"seller_inn":{"type":"string"},"amount":{"type":"string"}},
"required":["seller_inn","amount"]}'{
"result": { "seller_inn": "7707083893", "amount": "12500.00" },
"usage": { "pages": 1, "sheets": null },
"metadata": { "extraction_status": "full", "…": "…" }
}Схема, покрытая маппингом лишь частично, идет в модель как обычно — значения из XML подмешиваются поверх ее ответа, а не теряются. Новый формат — это новый файл описания, а не новый код; форматы ФНС из ЭДО (УПД, счет-фактура) добавляются по мере появления реальных образцов.
usage.sheets для XML — null: это единый структурный документ, а не набор
листов.
Лимиты
| Что | Ограничение | Что приходит при превышении |
|---|---|---|
Файл file | 50 МБ | 413 FILE_TOO_LARGE |
Реестр registry | 20 МБ | 413 FILE_TOO_LARGE, details.field: "registry" |
| XML — размер | 10 МБ | 422 XML_TOO_LARGE |
| XML — число элементов | 200 000 | 422 XML_TOO_COMPLEX |
prompt | ~10 000 знаков | 422 PROMPT_TOO_LONG |
| Время синхронного ответа | 300 с (внешний прокси) | обрыв соединения — используйте async |
| Хранение async-результата | 1 час | 404 TASK_NOT_FOUND |
Лимит промпта — не экономия, а граница смысла: промпт это инструкция, а не
содержимое. Если инструкция не помещается в 10 000 знаков, скорее всего в
нее попал текст документа — ему место в text.
Реестр больше 20 МБ — случай для SDK docai-match (сверка на вашей стороне)
или self-hosted-контура; см. страницу цен.
Что происходит с документом дальше
Документ и реестр обрабатываются в памяти запроса и не сохраняются. Разбор
кэшируется по хешу файла на час — несколько задач над одним документом не
оплачивают OCR дважды; факт попадания в кэш виден в metadata.cached, а сам
хеш — в metadata.file_hash.
output_schema
Как спроектировать JSON-схему ответа — типы, вложенность, массивы, описания как подсказки модели. Самый частый источник ошибок у новичков.
Ошибки и деградация
Три формы тела ошибки, полный каталог кодов /v1/process, extraction_status и warnings[] — как API сообщает о частичном или ненадежном результате.