Документация API

/v1/balance Возвращает текущий баланс scan pages для аккаунта по API-ключу. Используйте remaining_pages или total_affordable_pages, чтобы понять, сколько страниц еще можно обработать.

curl -X GET https://sotaocr.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "entity_code": "scan_page",
  "remaining_pages": 63,
  "total_affordable_pages": 63,
  "monthly_pages": {"total": 40, "allocated": 5, "remaining": 35},
  "lifetime_pages": {"total": 20, "allocated": 2, "remaining": 18},
  "tokens": {"total": 120, "allocated": 20, "remaining": 100, "affordable_pages": 10},
  "token_price": 10
}

/v1/extract Загружает PDF или изображение в OCR. При успехе возвращает 202 Accepted и метаданные джобы, включая account_id, upstream_job_id, created_at и updated_at.

• file: Файл документа (PDF, PNG, JPG, JPEG, WEBP, BMP, TIF, TIFF).
• page_ranges: (Опционально) JSON-строка с массивом диапазонов страниц. Пример: '[{"start":1,"end":3}]'
• model_profile: Опциональный профиль OCR-модели. Не передавайте поле, чтобы использовать дефолт сервиса, или передайте одно из значений model_profiles из GET /api/v1/info.

curl -X POST https://sotaocr.com/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'page_ranges=[{"start":1,"end":5}]'

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "pending",
  "page_count": 5,
  "pages_completed": 0,
  "model_profile": "fast",
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:00Z"
}

/v1/jobs/{job_id} Возвращает 200 OK с текущим статусом обработки и полями account_id, upstream_job_id, page_count, pages_completed, created_at и updated_at.

curl -X GET https://sotaocr.com/v1/jobs/job_123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "completed",
  "page_count": 5,
  "pages_completed": 5,
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:08Z"
}

/v1/jobs/{job_id}/result?format=markdown Возвращает 200 OK с распознанным содержимым, когда джоба завершена. Для format=json страницы могут содержать doc_preprocessor_res с angle и page_preview с metadata coordinate space для bbox. format=html возвращает реконструированный HTML внутри JSON envelope для FAST и PRO; для самостоятельного HTML-файла со встроенными картинками используйте /result.html. До завершения эндпоинт отвечает 202 Accepted с кодом result_not_ready.

• format: (Опционально) Формат ответа: json, markdown, text или html. По умолчанию json. html доступен для FAST- и PRO-моделей.

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result?format=markdown" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "job_id": "job_123456789",
  "format": "json",
  "page_count": 1,
  "content": "{\"job_id\":\"job_123456789\",\"page_count\":1,\"pages\":[{\"page_number\":1,\"status\":\"completed\",\"text\":\"Иван Матвеев\",\"doc_preprocessor_res\":{\"angle\":0,\"model_settings\":{\"use_doc_orientation_classify\":true,\"use_doc_unwarping\":false}},\"page_preview\":{\"coordinate_space\":\"doc_preprocessed\",\"content_type\":\"image/png\",\"width\":1192,\"height\":1684},\"raw_result\":{}}]}"
}

/v1/jobs/{job_id}/result.html Возвращает text/html реконструкцию со встроенными data-URI изображениями для FAST- и PRO-моделей.

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result.html" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.html

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Disposition: inline; filename="job_123456789.html"

(самостоятельный HTML со встроенными data-URI изображениями)

/v1/jobs/{job_id}/result.docx Возвращает бинарный .docx с визуальной реконструкцией, встроенными изображениями страниц и searchable OCR-текстом для FAST- и PRO-моделей.

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result.docx" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.docx

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="job_123456789.docx"

(бинарные DOCX bytes)

/v1/jobs/{job_id}/pages/{page_number}/preview Возвращает PNG-изображение страницы после автоматического поворота и условного unwarp. Это тот же image object, поверх которого нужно рисовать OCR bbox.

curl -X GET https://sotaocr.com/v1/jobs/job_123456789/pages/1/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output page_0001_preview.png

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: inline; filename="page_0001_preview.png"

(binary PNG bytes в той же системе координат, что и OCR bbox)

Большинство ошибок используют формат {"error":{"code":"...","message":"..."}}. Для insufficient_balance дополнительно приходят entity_code, requested_units и available_units.

• 400 Некорректный запрос: Неверный multipart, отсутствует file, некорректный page_ranges или битый документ. Код ошибки: bad_request.
• 401 Не авторизован: Bearer-токен отсутствует или невалиден. Код ошибки: unauthorized.
• 403 Доступ запрещен: Нет доступа к API или недостаточно баланса. Коды ошибок: api_access_required или insufficient_balance.
• 404 Не найдено: Неизвестный job_id или попытка доступа к чужой джобе. Код ошибки: job_not_found.
• 415 Неподдерживаемый тип: Неподдерживаемый тип загруженного файла. Код ошибки: unsupported_media.
• 502 Ошибка upstream: Upstream OCR недоступен или синхронизация джобы завершилась ошибкой. Код ошибки: upstream_unavailable.