# STT Control

이 API들은 Server를 재시작하거나 Stream을 다시 생성하지 않고도, Runtime 중 특정 Stream에 대한 실시간 Speech-to-Text (STT) 추론을 일시 중지하거나 재개할 수 있습니다.

전체 STT 구성 방법은 [Realtime Speech-to-Text](/guide/ko-kr/features/transcoding-and-processing/subtitles/realtime-speech-to-text.md)를 참조하십시오.

## Enable STT

Stream에 대한 STT 추론을 재개합니다. Audio Frame이 Whisper Model로 다시 전달되며, Subtitle Cue 생성도 다시 시작됩니다.

> #### Request

<details>

<summary><mark style="color:blue;">POST</mark> v1/vhosts/{vhost}/apps/{app}/streams/{stream}:enableStt</summary>

**Header**

```http
Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>
```

**Body**

```json
{}
```

</details>

> #### Responses

<details>

<summary><mark style="color:blue;">200</mark> Ok</summary>

The request has succeeded

**Header**

```
Content-Type: application/json
```

**Body**

```json
{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "enabled": true
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response.enabled
    true if STT is now running
```

</details>

<details>

<summary><mark style="color:red;">401</mark> Unauthorized</summary>

Authentication required

**Header**

```http
WWW-Authenticate: Basic realm="OvenMediaEngine"
```

**Body**

```json
{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}
```

</details>

<details>

<summary><mark style="color:red;">404</mark> Not Found</summary>

The given vhost, app, or stream name could not be found, or no STT encoder exists for this stream.

**Body**

```json
{
    "statusCode": 404,
    "message": "Could not find STT encoder for stream: [default/app/stream]"
}
```

</details>

<details>

<summary><mark style="color:red;">503</mark> Service Unavailable</summary>

The Transcoder module is not running.

</details>

## Disable STT

STT 추론을 일시 중지합니다. Audio Frame은 처리되지 않은 채 폐기되며, Subtitle Rendition은 Stream에 그대로 유지되지만 더 이상 새로운 Cue를 받지 않습니다. 기반이 되는 STT Model과 GPU 할당은 계속 로드된 상태로 유지됩니다.

> #### Request

<details>

<summary><mark style="color:blue;">POST</mark> v1/vhosts/{vhost}/apps/{app}/streams/{stream}:disableStt</summary>

**Header**

```http
Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>
```

**Body**

```json
{}
```

</details>

> #### Responses

<details>

<summary><mark style="color:blue;">200</mark> Ok</summary>

The request has succeeded

**Header**

```
Content-Type: application/json
```

**Body**

```json
{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "enabled": false
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response.enabled
    false if STT is now paused
```

</details>

<details>

<summary><mark style="color:red;">401</mark> Unauthorized</summary>

Authentication required

**Header**

```http
WWW-Authenticate: Basic realm="OvenMediaEngine"
```

**Body**

```json
{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}
```

</details>

<details>

<summary><mark style="color:red;">404</mark> Not Found</summary>

The given vhost, app, or stream name could not be found, or no STT encoder exists for this stream.

**Body**

```json
{
    "statusCode": 404,
    "message": "Could not find STT encoder for stream: [default/app/stream]"
}
```

</details>

<details>

<summary><mark style="color:red;">503</mark> Service Unavailable</summary>

The Transcoder module is not running.

</details>

## Get STT Status

해당 Stream의 활성화 상태와 활성화된 모든 STT Rendition Configuration을 반환 (조회)합니다.

> #### Request

<details>

<summary><mark style="color:blue;">POST</mark> v1/vhosts/{vhost}/apps/{app}/streams/{stream}:sttStatus</summary>

**Header**

```http
Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>
```

**Body**

```json
{}
```

</details>

> #### Responses

<details>

<summary><mark style="color:blue;">200</mark> Ok</summary>

The request has succeeded

**Header**

```
Content-Type: application/json
```

**Body**

```json
{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "enabled": true,
        "renditions": [
            {
                "codec": "WHISPER",
                "label": "Korean",
                "model": "whisper_model/ggml-small.bin",
                "language": "auto",
                "translation": "false"
            },
            {
                "codec": "WHISPER",
                "label": "English",
                "model": "whisper_model/ggml-small.bin",
                "language": "auto",
                "translation": "true"
            }
        ]
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response.enabled
    true if STT inference is currently running, false if paused
# response.renditions
    List of active STT encoder instances for this stream
    ## codec
        STT engine in use. Currently always "whisper".
    ## label
        Subtitle rendition label this instance writes to.
    ## model
        Model file path used by this instance.
    ## language
        Configured source language ("auto" or a language code).
    ## translation
        "true" if translation to English is enabled.
```

</details>

<details>

<summary><mark style="color:red;">401</mark> Unauthorized</summary>

Authentication required

**Header**

```http
WWW-Authenticate: Basic realm="OvenMediaEngine"
```

**Body**

```json
{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}
```

</details>

<details>

<summary><mark style="color:red;">503</mark> Service Unavailable</summary>

The Transcoder module is not running.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ovenmediaengine-enterprise.gitbook.io/guide/ko-kr/features/rest-api/v1/virtual-host/application/stream/stt-control.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.