Документация API проверки текста: запросы, статусы, ошибки

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

Задайте ASNAP_API_URL и ASNAP_API_KEY в окружении вашего сервера. В примере замените your-service на выданный идентификатор клиента.

1. Подготовьте request.json

{
  "client": "your-service",
  "text": "Текст вашей работы для проверки…",
  "modules": [
    "plagiarism",
    "ai"
  ],
  "parent_uid": "paper_revision_000001"
}

2. Отправьте текст

curl "$ASNAP_API_URL/v1/checks" \
  -H "X-API-Key: $ASNAP_API_KEY" \
  -H 'Content-Type: application/json' \
  --data @request.json

Успешный ответ — HTTP 202. Пример ответа:

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "status": "queued",
  "queue_position": 1
}

3. Получите результат

curl "$ASNAP_API_URL/v1/checks/$TASK_ID" \
  -H "X-API-Key: $ASNAP_API_KEY"

Сохраните task_id и опрашивайте статус с интервалом от 3 секунд. Остановитесь при ready или failed. Примеры идентификаторов и текста условные.

Авторизация и область доступа

Передавайте секретный ключ в заголовке X-API-Key. Значение client должно соответствовать проекту этого ключа. Не помещайте ключ в URL, браузерный JavaScript, публичный репозиторий или логи.

Если интеграция использует отдельные пользовательские балансы, передавайте согласованный целочисленный X-User-ID одинаково при создании, опросе и восстановлении задачи. Поле user_id, если оно задано, должно совпадать с заголовком. Схему балансов подключаем отдельно.

Создание задачи

POST /v1/checks, JSON, кодировка UTF-8.

Поле	Условия
`text`	Обязательно. 10–50 000 символов Unicode. Для содержательной оценки ИИ нужен оцениваемый текст от 3 000 символов.
`client`	Обязательно. Идентификатор, выданный для вашего ключа.
`modules`	`plagiarism`, `ai` или оба. По умолчанию — оба.
`parent_uid`	Рекомендуется. 16–64 символа A–Z, a–z, 0–9, _ или -. Постоянный идентификатор одного запуска.
`exclude_domains`	До 20 доменов для исключения из доли заимствований. Например, собственный сайт издания.
`input_provenance`	Необязательно. Происхождение текста: `direct_text` или `file_extraction`. При извлечении обязательны название и версия экстрактора; указанные длины должны соответствовать отправленному тексту.

Статусы и результат

GET /v1/checks/{task_id} возвращает статус, готовность и результат задачи.

queued: Задача принята и ждёт обработки.
processing: Проверка выполняется. progress отражает данные обработки.
ready: Основной результат готов. В result — доступные модули, источники и разметка.
failed: Проверка не выполнена. Изучите error и свяжитесь с поддержкой при повторении.

Блок антиплагиата содержит original_percent, plagiat_percent, citation_percent, sources и fragments. Блок ИИ — ai_percent, доступность оценки и разметку. Дополнение библиографии, если включено для проекта, может прийти после основного результата.

Проценты интерпретируйте вместе с источниками и ограничениями метода. Недоступную оценку ИИ не превращайте в 0%. Единицы смещений разметки соблюдайте по контракту ответа: Unicode и UTF-16 не взаимозаменяемы для emoji.

Повторы без дублирования

При потере ответа повторите тот же текст, модули и parent_uid. В пределах одного клиента и пользователя вернётся уже созданная задача. Изменённой версии текста нужен новый parent_uid.

GET /v1/checks/by-parent/{parent_uid} позволяет восстановить идентификатор задачи. При конфликте параметров старый ключ не переиспользуйте. Сетевые повторы ограничивайте и увеличивайте паузу между ними.

Ошибки HTTP

Код	Что проверить
400 / 422	Формат полей, объём, идентификатор пользователя и читаемость текста.
401 / 403	Наличие ключа, его client и область доступа. Автоматические повторы без изменения запроса не помогут.
402	Недостаточно символов при подключённом пользовательском балансе.
404	Задача отсутствует либо недоступна в текущей области клиента/пользователя.
409	Идентификатор запуска уже использован с другими параметрами.
429 / 5xx	Уменьшите частоту запросов. Для нового POST сохраняйте тот же parent_uid при повторе.

Лимиты, хранение и возможности пилота

Один запрос — текст до 50 000 символов. Частоту, параллельность, общий объём, хранение и условия списания согласуем для проекта. Возможности сайта по проверке 3 млн символов не означают такой же размер одного API-запроса.

Текст не добавляется автоматически в общий корпус сравнения. Запрос может содержать конфиденциальные данные: отправляйте его с серверной стороны по HTTPS и отдельно согласуйте требования к хранению. Ссылка на отчёт, если выдаётся, предоставляет доступ её владельцу.

В этой версии интеграции получение результата выполняется опросом. Публичные SDK, webhook, самостоятельная выдача ключей и покупка API-пакета в кабинете ещё не открыты. Не закладывайте эти возможности в работающую интеграцию.

Запросить подключение API