Операции¶
Операция — это объект фоновой задачи. Она используется и расширенным STT v1, и SpeechKit-совместимым STT v3: по идентификатору операции клиент отслеживает прогресс, получает результат, отменяет незавершённую задачу или очищает её содержимое.
Все методы требуют аутентификации: API-ключа в Authorization либо активной
cookie-сессии портала (см. Аутентификация).
Операция видна только своему владельцу; legacy-администратор портала видит все
операции. Для остальных обращение к чужому идентификатору завершается 404.
Список операций¶
Метод возвращает последние операции текущего пользователя от новых к старым. Администратор портала видит операции всех пользователей.
| Query-параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
done |
boolean | — | Фильтр по признаку завершения |
kind |
string | — | Фильтр по metadata.kind, например stt_v1_async или stt_v3_recognize_file |
limit |
integer | 20 |
Число элементов от 1 до 100 |
Пример получения активных фоновых распознаваний STT v1:
curl "https://api.speech.example.com/api/operations?done=false&kind=stt_v1_async&limit=20" \
-H "Authorization: Api-Key $API_KEY"
Ответ — JSON-массив объектов того же формата, который описан ниже для одного
идентификатора. Процент динамически уточняется для выполняющейся операции и
может содержать metadata.progress_is_estimated: true.
Получение статуса операции¶
Параметры пути¶
| Параметр | Описание |
|---|---|
operationId |
UUID операции |
Ответ — операция выполняется¶
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"description": null,
"createdAt": "2025-01-15T10:30:00.000000",
"modifiedAt": null,
"done": false,
"metadata": {
"kind": "stt_v3_recognize_file",
"status": "running",
"progress_stage": "running",
"progress_percent": 2,
"model": "SpeechExpert-STT",
"summarization": true,
"summarization_model": "google/gemini-3.1-flash-lite",
"summarization_properties": 2
},
"response": null,
"error": null
}
Ответ — операция завершена успешно (STT v3)¶
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2025-01-15T10:30:00.000000",
"modifiedAt": "2025-01-15T10:30:05.000000",
"done": true,
"response": {
"sessionUuid": {
"uuid": "...",
"userRequestId": "..."
},
"audioCursors": {
"receivedDataMs": "15000",
"resetTimeMs": "0",
"partialTimeMs": "15000",
"finalTimeMs": "15000",
"finalIndex": "0",
"eouTimeMs": "15000"
},
"responseWallTimeMs": "3200",
"final": {
"alternatives": [
{
"text": "распознанный текст",
"startTimeMs": "120",
"endTimeMs": "1380",
"confidence": "0",
"words": [
{"text": "распознанный", "startTimeMs": "120", "endTimeMs": "760"},
{"text": "текст", "startTimeMs": "820", "endTimeMs": "1380"}
],
"languages": [
{"languageCode": "ru-RU", "probability": "1"}
]
}
]
}
},
"error": null
}
Для metadata.kind="stt_v1_async" поле response имеет другую форму: это тот
же STTResponse, который возвращает синхронный
POST /api/stt/v1, например:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"done": true,
"metadata": {
"kind": "stt_v1_async",
"progress_stage": "completed",
"progress_percent": 100
},
"response": {
"result": "распознанный текст",
"words": [],
"segments": [],
"entities": null,
"summarization": null
},
"error": null
}
Ответ — операция завершена с ошибкой¶
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"done": true,
"response": null,
"error": {
"code": 500,
"message": "Internal error during recognition",
"details": [
{"type": "RuntimeError"}
]
}
}
Поля операции¶
| Поле | Тип | Описание |
|---|---|---|
id |
string | UUID операции |
description |
string / null | Описание задачи, если оно было задано при создании |
done |
boolean | true — операция завершена, false — выполняется |
createdAt |
string | Время создания (ISO 8601) |
createdBy |
string / null | Владелец операции; доступ к чужим операциям скрыт ответом 404 |
modifiedAt |
string / null | Время последнего обновления |
metadata |
object / null | Служебные метаданные задачи: тип, модель, статус, прогресс и включённые этапы обработки |
response |
object / null | Результат при успехе: STTResponse для v1 либо GetRecognitionResponse для v3 |
error |
object / null | Информация об ошибке (при неудаче) |
error.code — сохранённый HTTP status фоновой ошибки (обычно 500), а не код
gRPC. details содержит безопасные структурированные сведения, например имя
класса исключения; traceback и внутренние данные клиенту не возвращаются.
Как прочитать результат
У операции STT v1 итоговый текст находится в response.result; поля
utterances, segments, entities и summarization зависят от параметров
запуска. У STT v3 текст находится в
response.final.alternatives[0].text. Если была запрошена нормализация или
другая финальная обработка, здесь уже находится обработанная версия;
нативные offsets Riva FastConformer находятся в
response.final.alternatives[0].words.
Для STT v3 каноническая последовательность уже сохранена в
response.recognitionEvents. После появления done: true те же события
можно последовательно прочитать методом
GET /api/stt/v3/getRecognition,
передав тот же идентификатор операции.
metadata.progress_percent — число от 0 до 100. Общие стадии — queued,
running, completed, failed и cancelled. STT v1 во время работы уточняет
их до предметных стадий, например loading_audio, validating_url,
extracting_media, downloading_audio, audio_downloaded,
detecting_format, converting_audio, audio_converted, prepared, recognizing,
recognizing_and_diarizing, recognizing_channels, correcting_text,
extracting_entities, summarizing, recording_saved и finalizing. Не каждая стадия появляется
в каждом запросе. Во время ASR процент может быть расчётным — тогда в metadata
есть progress_is_estimated: true. После завершения процент всегда равен 100,
в том числе при ошибке или отмене.
STT v3 дополнительно сохраняет в metadata выбранную модель, параметры диаризации и, если включена суммаризация, её фактическую серверную модель и число инструкций. STT v1 сохраняет выбранный источник, язык, режим каналов, флаги LLM-этапов и приватного режима, чтобы Playground мог восстановить задачу.
Отмена операции¶
Отменяет операцию, которая ещё выполняется. Уже завершённую операцию отменить нельзя.
Параметры пути¶
| Параметр | Описание |
|---|---|
operationId |
UUID операции |
Пример¶
curl -X POST "https://api.speech.example.com/api/operations/550e8400-e29b-41d4-a716-446655440000:cancel" \
-H "Authorization: Api-Key $API_KEY"
Удаление содержимого операции¶
Для завершённой операции безвозвратно очищает response и error. У приватной
операции также удаляются description, staged upload и идентифицирующие источник
metadata; остаются только владелец, статус, модель, флаги режима, длительность,
размеры и временные метки, необходимые для billing/audit. У обычной операции в
metadata ставится content_purged=true.
Метод возвращает 204 No Content, доступен владельцу (и legacy-администратору)
и идемпотентен по смыслу. Для ещё выполняющейся операции возвращается 409.
Playground вызывает этот метод автоматически после получения результата в приватном режиме. Если клиент отключился до очистки, сервер применяет резервный TTL.
Пример: опрос статуса STT v3 на Python¶
import requests
import time
BASE_URL = "https://api.speech.example.com"
HEADERS = {"Authorization": "Api-Key <ваш-ключ>"}
operation_id = "550e8400-e29b-41d4-a716-446655440000"
while True:
resp = requests.get(f"{BASE_URL}/api/operations/{operation_id}", headers=HEADERS)
operation = resp.json()
if operation["done"]:
if operation.get("error"):
print(f"Ошибка: {operation['error']['message']}")
else:
text = operation["response"]["final"]["alternatives"][0]["text"]
print(f"Результат: {text}")
break
time.sleep(2)
Ошибки¶
| Код | Когда возникает |
|---|---|
400 |
Попытка отменить уже завершённую операцию |
401 |
Не аутентифицирован (отсутствует или неверный API-ключ) |
404 |
Операция с таким идентификатором не найдена (или принадлежит другому владельцу) |
409 |
Попытка очистить содержимое ещё выполняющейся операции |
500 |
Не удалось удалить staged upload приватной операции |