Операции¶

Операция — это объект фоновой задачи. Она используется и расширенным STT v1, и SpeechKit-совместимым STT v3, и фоновым синтезом длинного текста: по идентификатору операции клиент отслеживает прогресс, получает результат, отменяет незавершённую задачу или очищает её содержимое.

Все методы требуют аутентификации: API-ключа в Authorization либо активной cookie-сессии портала (см. Аутентификация). Операция видна только своему владельцу. Обращение к чужому идентификатору завершается 404.

У фонового TTS отдельные управляющие маршруты

Приватная TTS-операция видна в общем списке с metadata.kind="tts_v1_long_async", но для статуса, остановки, возобновления и скачивания используйте /api/tts/v1/operations/.... Публичная TTS-операция работает без аккаунта только через /api/public/tts/v1/operations/... на выделенном домене и требует X-TTS-Operation-Token. Полный контракт описан на отдельной странице.

Список операций¶

GET /api/operations

Метод возвращает последние операции текущего пользователя от новых к старым.

Query-параметр	Тип	По умолчанию	Описание
`done`	boolean	—	Фильтр по признаку завершения
`kind`	string	—	Фильтр по `metadata.kind`, например `stt_v1_async`, `stt_v3_recognize_file` или `tts_v1_long_async`
`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.

Получение статуса операции¶

GET /api/operations/{operationId}

Параметры пути¶

Параметр	Описание
`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-RU",
    "summarization": true,
    "summarization_model": "google/gemini-3.5-flash-lite-minimal",
    "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` для STT v1, `GetRecognitionResponse` для STT v3 либо ссылка на WAV и его длительность для фонового TTS
`error`	object / null	Информация об ошибке (при неудаче)

error.code — сохранённый HTTP status фоновой ошибки (обычно 500), а не код gRPC. details содержит безопасные структурированные сведения; диагностические данные сервиса клиенту не возвращаются.

Как прочитать результат

У операции STT v1 итоговый текст находится в response.result; поля utterances, segments, entities и summarization зависят от параметров запуска. У STT v3 текст находится в response.final.alternatives[0].text. Если была запрошена нормализация или другая финальная обработка, здесь уже находится обработанная версия. Таймкоды слов находятся в 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 мог восстановить задачу.

Операции фонового TTS¶

У длинного TTS metadata.kind="tts_v1_long_async". Он добавляет число готовых фрагментов, признаки полного/частичного результата и возможность продолжения. Поле response.audio_url указывает на отдельный бинарный endpoint: сам WAV в JSON операции не включается.

В отличие от общих STT-операций, фоновый TTS:

после :cancel собирает доступный partial;
поддерживает :resume для отменённой или ошибочной задачи;
хранит готовые фрагменты до истечения срока хранения;
удаляет аудио и входные данные по TTL.

Маршруты, публичный capability-token, примеры и правила тарификации приведены в разделе Фоновый синтез длинного текста.

Отмена операции¶

POST /api/operations/{operationId}:cancel

Отменяет операцию, которая ещё выполняется. Уже завершённую операцию отменить нельзя.

Не используйте этот маршрут для длинного TTS

Для фонового TTS предусмотрен отдельный маршрут POST /api/tts/v1/operations/{id}:cancel.

Параметры пути¶

Параметр	Описание
`operationId`	UUID операции

Пример¶

curl -X POST "https://api.speech.example.com/api/operations/550e8400-e29b-41d4-a716-446655440000:cancel" \
  -H "Authorization: Api-Key $API_KEY"

Удаление содержимого операции¶

POST /api/operations/{operationId}:purge

Для завершённой операции безвозвратно очищает response, error, описание и связанные входные файлы. Остаются только владелец, статус, модель, параметры режима, длительность, размеры и временные метки. В metadata ставится content_purged=true.

Метод возвращает 204 No Content, доступен владельцу и идемпотентен по смыслу. Для ещё выполняющейся операции возвращается 409.

Для фоновой TTS-операции метод также удаляет голосовой референс, WAV-фрагменты, частичный и итоговый WAV. При ошибке удаления API возвращает 500 и не выставляет content_purged=true.

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`	Не удалось удалить содержимое операции

Операции¶

Список операций¶

Получение статуса операции¶

Параметры пути¶

Ответ — операция выполняется¶

Ответ — операция завершена успешно (STT v3)¶

Ответ — операция завершена с ошибкой¶

Поля операции¶

Операции фонового TTS¶

Отмена операции¶

Параметры пути¶

Пример¶

Удаление содержимого операции¶

Пример: опрос статуса STT v3 на Python¶

Ошибки¶

См. также¶