Defectoscopy — начало работы

Defectoscopy принимает изображение, ставит задачу в очередь и возвращает результат классификации дефектов и поверхности. Полная машиночитаемая спецификация — на странице Defectoscopy API и в openapi.json. Здесь — краткий обзор и рабочие примеры для старта.

Среды

Среда	URL
Прод	https://defects.techcon-ml.ru
Дев-стенд	https://defects.dev.techcon-ml.ru
Локальная	http://localhost:8000

Аутентификация

Все эндпоинты, кроме GET /health, требуют заголовок Authorization: Bearer <токен>. Токен выдаёт владелец сервиса.

Матрица защиты

Публичный домен defects.techcon-ml.ru — лёгкий always-on приёмный слой («Public Trigger»), который принимает запрос и будит обработку по требованию. Ниже — весь его маршрут целиком, без исключений:

Эндпоинт	Метод	Требуется токен
/health	GET	Нет
/predict	POST	Да (Bearer)
/result/{task_id}	GET	Да (Bearer)

⚠ Более ранняя редакция этого гайда несла /classes/* и /ops/* как будто это тоже публичные маршруты. Формулировка была неверной: эти пути принадлежат отдельному внутреннему приложению (полный обработчик на GPU-картах) и никогда не были зарегистрированы на публичном домене. Живая проверка 01.09.2026 подтвердила: все они отвечают 404 на defects.techcon-ml.ru. Используйте только три маршрута выше.

Общие ограничения

• Ограничение нагрузки: 1000 запросов в минуту на токен (по умолчанию). При превышении — 429 RATE_LIMIT_EXCEEDED с полем retry_after_seconds.
• image_url в POST /predict — только https://, хост обязан быть storage.yandexcloud.net или storage.yc.yandex.net.
• Максимальный размер запроса и таймаут — не заданы отдельно от значений по умолчанию используемого HTTP-сервера.

Проверка состояния

curl -s https://defects.dev.techcon-ml.ru/health

{
  "ok": true,
  "data": {
    "model_loaded": true,
    "model_version": "v10"
  }
}

Пока модель не загружена, ответ — 503 с кодом MODEL_NOT_READY.

Постановка задачи

POST /predict принимает ссылку на изображение и сразу возвращает 202 Accepted с task_id. Итог читайте через GET /result/{task_id}.

curl -X POST https://defects.techcon-ml.ru/predict \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "image_url": "https://storage.yandexcloud.net/techconimg/zT1RP8i7vfpj",
    "priority": "batch"
  }'

import httpx

resp = httpx.post(
    "https://defects.techcon-ml.ru/predict",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "image_url": "https://storage.yandexcloud.net/techconimg/zT1RP8i7vfpj",
        "priority": "batch",
    },
)
print(resp.status_code, resp.json())

Ответ:

{
  "ok": true,
  "data": {
    "task_id": "def-7a2d8f5d0f31",
    "status": "queued",
    "status_url": "/result/def-7a2d8f5d0f31",
    "accepted_at": "1745271600",
    "estimated_wait_seconds": 90,
    "wait_hint_is_advisory": true,
    "poll_interval_seconds_min": 30,
    "poll_interval_seconds_max": 60,
    "result_ttl_seconds": 86400
  }
}

estimated_wait_seconds — ориентир для первого повторного запроса, не обещание по времени (wait_hint_is_advisory: true). Дополнительные поля запроса:

• priority — realtime или batch (по умолчанию batch);
• surface — необязательная поверхность, если она известна заранее (например, «Внутренние стены»); ускоряет и уточняет классификацию;
• force_reprocess — true, чтобы принудительно пересчитать результат вместо уже закешированного для того же изображения;
• webhook_url — см. раздел «Обратный вызов» ниже.

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

data.status	HTTP	Значение
queued	202	задача принята и ждёт обработки
processing	202	задача обрабатывается
done	200	классификация завершена успешно
failed	200	обработка завершилась ошибкой

curl -s https://defects.techcon-ml.ru/result/def-7a2d8f5d0f31 \
  -H "Authorization: Bearer $TOKEN"

Успешный итог (200, status: done):

{
  "ok": true,
  "data": {
    "task_id": "def-7a2d8f5d0f31",
    "status": "done",
    "accepted_at": "1745271600",
    "started_at": "1745271660",
    "completed_at": "1745271700",
    "processing_time_ms": 1234,
    "result": {
      "surface": "металл",
      "masters": [{"name": "механические", "conf": 0.82}],
      "defects": [{"name": "царапина", "conf": 0.75}]
    },
    "result_ttl_seconds": 86400
  }
}

Ошибка обработки (200, status: failed):

{
  "ok": true,
  "data": {
    "task_id": "def-7a2d8f5d0f31",
    "status": "failed",
    "accepted_at": "1745271600",
    "started_at": "1745271660",
    "failed_at": "1745271700",
    "result_ttl_seconds": 86400,
    "error": "Не удалось обработать изображение"
  }
}

Продолжайте опрос с паузой 30–60 секунд на задачу, пока статус не станет done или failed. Результат хранится 86400 секунд — после истечения GET /result/{task_id} для того же task_id вернёт 404 TASK_NOT_FOUND.

Обратный вызов (webhook)

webhook_url в POST /predict добавляет необязательный обратный вызов после итогового состояния задачи — он не заменяет опрос GET /result/{task_id}. Значение можно передать строкой (URL) или объектом {"url": "...", "secret": "..."}.

{
  "image_url": "https://storage.yandexcloud.net/techconimg/zT1RP8i7vfpj",
  "webhook_url": {
    "url": "https://integrator.example.com/hooks/defectoscopy",
    "secret": "shared-secret"
  }
}

Тело обратного вызова повторяет формат GET /result/{task_id} для итогового состояния. Заголовки:

Заголовок	Значение
X-Techcon-Event	defectoscopy.result.terminal
X-Techcon-Task-ID	исходный task_id
X-Techcon-Delivery-ID	идентификатор доставки
X-Techcon-Defecto-Signature	только если передан secret: sha256=<hex> — HMAC-SHA256 от байтов тела запроса

Для проверки подписи вычислите HMAC-SHA256(secret, тело_запроса) и сравните результат в шестнадцатеричном виде со значением после sha256=.

Справочники классов

curl -s https://defects.techcon-ml.ru/classes/defects -H "Authorization: Bearer $TOKEN"

{"ok": true, "data": ["царапина", "трещина"]}

GET /classes/surfaces возвращает список поддерживаемых поверхностей в том же формате.

Типовые коды ошибок

Код	HTTP	Описание
UNAUTHORIZED	401	Токен отсутствует или неверен
TASK_NOT_FOUND	404	task_id неизвестен или результат истёк по времени хранения
VALIDATION_ERROR	422	Вход не прошёл проверку (например, недопустимый хост image_url)
RATE_LIMIT_EXCEEDED	429	Превышен лимит запросов
AUTH_NOT_CONFIGURED	503	Аутентификация на сервере не настроена
QUEUE_UNAVAILABLE	503	Очередь задач временно недоступна
MODEL_NOT_READY	503	Модель ещё не загружена
INTERNAL_ERROR	500	Внутренняя ошибка сервиса

Типовой сквозной сценарий

1. Проверить готовность: GET /health.
2. Поставить задачу: POST /predict с image_url.
3. Опрашивать GET /result/{task_id} с паузой 30–60 секунд, пока статус не станет done или failed.
4. При необходимости уточнить справочники: GET /classes/defects, GET /classes/surfaces.

Полный перечень полей, схем и кодов ответов — в автоматически собранной спецификации на странице Defectoscopy API.