Перейти к содержимому
TechCon ML Docs

Принять асинхронный STT-запрос

POST
/transcribe/audio_url
curl --request POST \
  --url https://stt.techcon-ml.ru/transcribe/audio_url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://storage.yandexcloud.net/techconimg/example-ru-speech.wav", "metadata": { "source": "demo-request", "locale": "ru-RU" }, "webhook": { "url": "https://integrator.example/hooks/stt", "secret": "stt-demo-secret" } }'

Принимает STT-задачу в общий постоянно доступный слой. После 202 Accepted интегратор должен сохранить task_id, status_url и estimated_wait_seconds. Первый полезный опрос результата обычно имеет смысл не раньше estimated_wait_seconds: около 60 секунд при уже запущенном worker и около 180 секунд при холодном или неопределённом состоянии. webhook может быть дополнительным сигналом, но не заменяет GET /result/{task_id}.

Authorizations

Заголовок раздела «Authorizations»

Request Bodyrequired

Заголовок раздела «Request Bodyrequired»
Media typeapplication/json
object
url
required

HTTPS URL на аудиофайл по адресу, который проходит общую проверку https:// и имени хоста.

string format: uri
Example
https://storage.yandexcloud.net/techconimg/example-ru-speech.wav
metadata

Дополнительные метаданные, которые будут сохранены рядом с задачей.

object
key
additional properties
any
webhook
object
url
required

HTTPS URL для уведомления о результате.

string format: uri
Example
https://integrator.example/hooks/stt
secret

Необязательный секрет для подписи или проверки webhook.

string
Example
stt-demo-secret
Example
{
  "url": "https://storage.yandexcloud.net/techconimg/example-ru-speech.wav",
  "metadata": {
    "source": "demo-request",
    "locale": "ru-RU"
  },
  "webhook": {
    "url": "https://integrator.example/hooks/stt",
    "secret": "stt-demo-secret"
  }
}

Responses

Заголовок раздела «Responses»

202

Заголовок раздела «202»

Запрос принят слоем приёма и поставлен в очередь.

Media typeapplication/json
object
ok
required
boolean
data
required
object
task_id
required
string
status
required
string
status_url
required
string
estimated_wait_seconds
required
integer
metadata
object
key
additional properties
any
webhook
object
configured
required
boolean
status
required
string
Example
{
  "data": {
    "status": "queued",
    "status_url": "/result/stt-123",
    "estimated_wait_seconds": 180,
    "webhook": {
      "status": "pending"
    }
  }
}

401

Заголовок раздела «401»

Bearer-токен отсутствует или неверен.

Media typeapplication/json
object
ok
required
boolean
error
required
object
code
required
string
message
required
string
Example
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Bearer-токен отсутствует или неверен."
  }
}

422

Заголовок раздела «422»

Входные данные не прошли проверку.

Media typeapplication/json
object
ok
required
boolean
error
required
object
code
required
string
message
required
string
Example
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Поле url должно быть непустым HTTPS-адресом."
  }
}

429

Заголовок раздела «429»

Превышен лимит запросов на токен.

Media typeapplication/json
object
ok
required
boolean
error
required
object
code
required
string
message
required
string
Example
{
  "ok": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Превышен лимит запросов на токен."
  }
}

Headers

Заголовок раздела «Headers»
Retry-After
string
Example
60

Через сколько секунд безопасно повторить запрос.

503

Заголовок раздела «503»

STT-задача не была поставлена в очередь: либо Redis недоступен, либо не настроен канонический набор Bearer-токенов.

Media typeapplication/json
object
ok
required
boolean
error
required
object
code
required
string
message
required
string
Example
{
  "ok": false,
  "error": {
    "code": "QUEUE_UNAVAILABLE",
    "message": "STT-задача не была поставлена в очередь: очередь сейчас недоступна."
  }
}