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

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

Сервис распознаёт русскоязычную речь. На другом языке или на музыке без речи результатом будет пустая строка — это не ошибка.

Среды

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

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

Требуется заголовок Authorization: Bearer <токен>. Токен выдаёт владелец сервиса. Без токена или с неверным токеном сервис отвечает 401 UNAUTHORIZED.

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

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

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

⚠ Более ранняя редакция этого гайда называла /classify/*, /taxonomy, /ops/* и /metrics «совместимыми маршрутами для старых клиентов» — формулировка была неверной: эти пути принадлежат отдельному внутреннему приложению (полный обработчик, который запускается на GPU-картах) и никогда не были зарегистрированы на публичном домене. Живая проверка 01.09.2026 подтвердила: все они отвечают 404 на stt.techcon-ml.ru. Используйте только три маршрута выше — это весь публичный API сервиса.

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

• Ограничение нагрузки: порядка 1000 запросов в минуту на токен. При превышении — 429 RATE_LIMIT_EXCEEDED с заголовком Retry-After.
• url в POST /transcribe/audio_url — ссылка на аудиофайл, доступная сервису на чтение.
• Максимальный размер запроса и таймаут отдельно не заданы сверх значений по умолчанию используемого HTTP-сервера.

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

curl -s https://stt.techcon-ml.ru/health

{
  "ok": true,
  "data": {
    "status": "ok",
    "public_mode": "runtime-ready",
    "request_acceptance": true,
    "startup_estimate_seconds": 180,
    "runtime_ready_timeout_seconds": 900,
    "cold_start_timeout_seconds": 900,
    "operator_action": "none"
  }
}

200 означает, что слой приёма готов принять задачу, но не гарантирует мгновенную обработку: при «холодном» состоянии сервис ещё прогревается, и первый результат появится позже (см. тайминги ниже). 503 означает, что слой временно не принимает новые задачи. Для проверки конкретной задачи используйте GET /result/{task_id}, а не /health.

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

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

curl -X POST https://stt.techcon-ml.ru/transcribe/audio_url \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://storage.yandexcloud.net/techconimg/example-ru-speech.wav",
    "metadata": {"report_defect_id": 123, "defect_name": "трещина"}
  }'

import httpx

resp = httpx.post(
    "https://stt.techcon-ml.ru/transcribe/audio_url",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "url": "https://storage.yandexcloud.net/techconimg/example-ru-speech.wav",
        "metadata": {"report_defect_id": 123, "defect_name": "трещина"},
    },
)
print(resp.status_code, resp.json())

Ответ (202):

{
  "ok": true,
  "data": {
    "task_id": "stt-42e11f77f737",
    "status": "queued",
    "status_url": "/result/stt-42e11f77f737",
    "estimated_wait_seconds": 180,
    "runtime": {
      "estimated_wait_seconds": 180,
      "poll_retry_interval_seconds": 60,
      "retention_seconds": 86400
    }
  }
}

Сохраните task_id и status_url — по ним вы будете забирать результат. Дополнительные поля запроса:

• metadata — произвольные данные; сервис вернёт их вместе с результатом без изменений;
• webhook — необязательный обратный вызов (см. раздел «Обратный вызов» ниже); вспомогательный канал, не замена опроса.

Ошибки.

Статус-код	Код	Причина
401	UNAUTHORIZED	нет токена или токен неверный
422	VALIDATION_ERROR	некорректное тело запроса (например, отсутствует url)
429	RATE_LIMIT_EXCEEDED	превышен лимит запросов на токен
503	REDIS_UNAVAILABLE	слой приёма временно не может безопасно принять задачу

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

GET /result/{task_id}   ->  202  (status: queued | processing)   повторять
GET /result/{task_id}   ->  200  (status: done | failed)         терминал

curl -H "Authorization: Bearer $TOKEN" \
  https://stt.techcon-ml.ru/result/stt-42e11f77f737

Ответ 200 при done:

{
  "ok": true,
  "data": {
    "task_id": "stt-42e11f77f737",
    "status": "done",
    "result": {
      "transcription": "трещина на фасаде",
      "service": "stt"
    },
    "processing_time_ms": 3500,
    "completed_at": "1234567890",
    "metadata": {
      "report_defect_id": 123,
      "defect_name": "трещина"
    }
  }
}

Если в аудио не нашлось полезной речи (тишина, музыка, речь на другом языке), задача всё равно завершается статусом done с пустой строкой result.transcription: "" — это корректный ответ, а не ошибка.

Ответ 200 при failed (внутренняя ошибка обработки, например тайм-аут скачивания файла):

{
  "ok": true,
  "data": {
    "task_id": "stt-42e11f77f737",
    "status": "failed",
    "error": "download timeout",
    "failed_at": "1234567890"
  }
}

Ошибки.

Статус-код	Код	Причина
401	UNAUTHORIZED	нет токена или токен неверный
404	TASK_NOT_FOUND	неизвестный task_id или истёкшее окно хранения
503	REDIS_UNAVAILABLE	слой чтения временно недоступен

Тайминги и ограничения

Параметр	Значение	Что означает
estimated_wait_seconds	60 (сервис «тёплый») или 180 (холодный старт)	через сколько имеет смысл сделать первый опрос результата
Интервал опроса	не чаще 1 раза в 60 секунд	как часто повторять GET /result/{task_id} после ответа 202
Окно хранения результата	86400 секунд (24 часа)	сколько результат доступен по GET /result/{task_id}

Окно хранения отсчитывается от момента приёма задачи, а не от её завершения: если задача обрабатывалась долго, после терминального статуса до очистки может остаться меньше полных 24 часов. Забирайте результат не откладывая.

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

webhook — вспомогательный канал уведомления. Он не заменяет GET /result/{task_id}: итог всегда нужно подтверждать опросом.

{
  "url": "https://storage.yandexcloud.net/techconimg/example-ru-speech.wav",
  "webhook": {
    "url": "https://integrator.example/hooks/stt",
    "secret": "ваш-секрет"
  }
}

Сервис уведомляет о результате POST-запросом на webhook.url при достижении статуса done или failed. Тело повторяет терминальный ответ GET /result/{task_id} и добавляет поля event и delivery_id.

Заголовок	Значение
X-Techcon-STT-Event	тип события
X-Techcon-STT-Delivery-Id	идентификатор доставки
X-Techcon-STT-Task-Id	исходный task_id
X-Techcon-STT-Signature	только если передан secret: HMAC-SHA256 от байтов тела запроса

Признак успешной доставки — любой ответ 2xx. Сервис повторяет доставку, пока не получит 2xx или пока действует окно хранения результата. Отбрасывайте повторные доставки по delivery_id и после получения webhook всё равно перепроверяйте итог через GET /result/{task_id}.

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

Код	HTTP	Описание
UNAUTHORIZED	401	Токен отсутствует или неверен
TASK_NOT_FOUND	404	task_id неизвестен или результат истёк по времени хранения
VALIDATION_ERROR	422	Вход не прошёл проверку
RATE_LIMIT_EXCEEDED	429	Превышен лимит запросов
REDIS_UNAVAILABLE	503	Слой приёма или чтения временно недоступен
MODEL_NOT_LOADED	503	Модель распознавания ещё не готова

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

1. Поставьте задачу через POST /transcribe/audio_url.
2. Сохраните task_id и status_url из ответа 202.
3. Первый опрос GET /result/{task_id} делайте не раньше estimated_wait_seconds.
4. Пока приходит 202, повторяйте опрос не чаще 1 раза в 60 секунд.
5. Дождитесь 200 со статусом done (или failed) и заберите result.transcription.
6. Даже при настроенном webhook подтверждайте итог через GET /result/{task_id}.

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