> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# 개요

> WebSocket으로 오디오를 보내고 전사와 번역 결과를 실시간으로 받는 실시간 전사 API의 동작 순서, 이용 조건, 제한을 설명해요.

엔터프라이즈 실시간 전사 API는 엔터프라이즈 플랜 고객에게 별도 문의로 제공하는 기능이에요. 모든 워크스페이스에 열려 있지 않아요. Tiro가 워크스페이스에 이 API를 켜야 호출할 수 있어요.

## 실시간 전사 API는 무엇을 하나요?

실시간 전사 API는 앱이 보내는 오디오를 받아 전사 결과를 바로 돌려줘요. 세션을 만들 때 번역 언어를 지정하면 번역 결과도 함께 받아요.

결과는 WebSocket 메시지로만 전달해요. Tiro는 이 API로 노트를 만들지 않고 받은 오디오를 보관하지 않아요. 전사와 번역 텍스트를 나중에 다시 조회하는 API도 없으니, 필요한 결과는 받는 쪽에서 저장하세요.

## 어떤 순서로 동작하나요?

실시간 전사는 REST로 세션을 만들고, WebSocket으로 오디오를 보내고 결과를 받아요. API Key는 고객 서버에만 두고, 클라이언트에는 세션마다 발급되는 `streamToken`만 넘겨요.

```mermaid theme={"system"}
sequenceDiagram
    participant S as 고객 서버
    participant C as 고객 클라이언트
    participant R as Tiro REST API
    participant W as Tiro WebSocket

    S->>R: POST /v1/external/realtime-transcriptions (API Key)
    R-->>S: 201 {id, wsUrl, streamToken}
    S->>C: wsUrl, streamToken 전달
    C->>W: wsUrl 연결 (Authorization: Bearer streamToken)
    W-->>C: session.started
    loop 녹음하는 동안
        C->>W: PCM 오디오 (바이너리 프레임)
        W-->>C: transcript, translation
    end
    C->>W: session.end
    W-->>C: 남은 transcript, translation (isFinal: true)
    W-->>C: session.ended 후 close 1000
```

| 단계 | 하는 일 | 자세히 |
| - | - | - |
| 1. 세션 만들기 | 고객 서버가 API Key로 세션을 만들고 `wsUrl`과 `streamToken`을 받아요 | [API 레퍼런스](https://docs.tiro.ooo/api-reference/realtime-transcription/create-realtime-transcription.md) |
| 2. 연결하기 | 클라이언트가 `streamToken`을 `Authorization` 헤더에 넣어 `wsUrl`에 연결해요 | [연결](https://docs.tiro.ooo/ko/developers/realtime-transcription/protocol.md#handshake) |
| 3. 오디오 보내고 결과 받기 | 16 kHz mono PCM을 보내고 `transcript`, `translation` 메시지를 받아요 | [메시지](https://docs.tiro.ooo/ko/developers/realtime-transcription/protocol.md#messages) |
| 4. 끝내기 | `session.end`를 보내면 Tiro가 남은 결과를 보내고 세션을 닫아요 | [종료](https://docs.tiro.ooo/ko/developers/realtime-transcription/protocol.md#ending) |

연결이 끊겨도 세션이 열려 있으면 같은 토큰으로 다시 연결해 이어 갈 수 있어요. 규칙은 [재접속](https://docs.tiro.ooo/ko/developers/realtime-transcription/protocol.md#reconnect)에 있어요.

## 누가 쓸 수 있나요?

아래 세 조건을 모두 갖춰야 세션을 만들 수 있어요.

| 조건 | 갖추지 못하면 |
| - | - |
| 엔터프라이즈 플랜 계약이 있고, Tiro가 워크스페이스에 실시간 전사 API를 켜 두었어요. 사용하려면 아래 문의 버튼으로 연락해 주세요 | `403` `realtime_api_not_enabled` |
| 워크스페이스에 묶인 API Key를 써요. 워크스페이스 API Key나 워크스페이스에 묶인 계정 API Key가 해당해요. 계정 API Key라면 키 주인이 그 워크스페이스 구성원이어야 해요 | `403` `workspace_bound_key_required` 또는 `workspace_access_denied` |
| Scope를 지정한 키라면 필요한 scope가 있어요. 세션 생성과 종료에는 `realtime_transcription:write`, 조회와 목록에는 `realtime_transcription:read`가 필요해요. `write`는 `read`를 포함해요 | `403` `insufficient_scope` |

조직 API Key와 OAuth 액세스 토큰으로는 이 API를 호출할 수 없어요. Scope는 [인증](https://docs.tiro.ooo/ko/developers/fundamentals/authentication.md)에서 자세히 설명해요.

## 어떤 제한이 있나요?

| 항목 | 값 | 넘으면 |
| - | - | - |
| 동시 세션 | 워크스페이스당 `OPEN` 세션 10개. API Key와 사용자를 가리지 않고 합산해요 | 세션 생성이 `409` `concurrent_transcription_limit`로 실패해요 |
| 오디오 없음 | 15분. 세션 생성 시각이나 마지막 오디오 프레임부터 재요 | 세션이 `IDLE_TIMEOUT`으로 끝나요 |
| 세션 최대 길이 | 3시간. 첫 연결부터 재고, 연결이 끊긴 시간도 포함해요 | 세션이 `MAX_DURATION`으로 끝나요 |
| 오디오 형식 | 16,000 Hz, mono, signed 16-bit little-endian PCM | 홀수 바이트 프레임이면 Tiro가 연결을 닫아요 |
| 오디오 프레임 크기 | 최대 6,400바이트(200 ms). 3,200바이트(100 ms)를 권장해요 | Tiro가 연결을 닫아요 |
| 오디오 선행량 | 실제 경과 시간보다 최대 60초 앞서 보낼 수 있어요 | Tiro가 close `4029`로 연결을 닫아요. 기다렸다가 다시 연결하세요 |
| REST 호출 | API Key당 60초에 600회 | `429`와 `Retry-After`를 받아요 |

> [!WARNING]
>
> 세션을 다 쓰면 `session.end`를 보내거나 `POST /v1/external/realtime-transcriptions/{id}/end`를 호출하세요. WebSocket 연결만 닫으면 세션은 `OPEN`으로 남아요. 오디오 없이 15분이 지나 자동으로 끝날 때까지 동시 세션 한 자리를 차지하고, 정리가 최대 3분쯤 더 늦을 수 있어요.

## 어떤 언어를 지원하나요?

전사와 번역 모두 [지원 로케일](https://docs.tiro.ooo/ko/developers/fundamentals/supported-locales.md)의 17개 로케일을 지원해요. 세션을 만들 때 `transcriptionLocale`을 생략하거나 `AUTO`로 보내면 Tiro가 말하는 언어를 자동으로 감지해요. `translationLocale`은 하나만 지정할 수 있고 자동 감지를 쓸 수 없어요.

번역은 원문 문장과 1:1로 짝지어 오지 않아요. 번역 조각을 도착한 순서대로 이어 붙여 보여 주세요. 규칙은 [`translation` 메시지](https://docs.tiro.ooo/ko/developers/realtime-transcription/protocol#translation)에 있어요.

## 이 API가 제공하지 않는 것은 무엇인가요?

지금 버전은 아래 기능을 제공하지 않아요.

* 화자 구분, 단어나 문장 단위 타임스탬프
* 노트 생성과 웹훅
* 오디오 보관과 재전송. 연결이 끊긴 동안의 오디오는 클라이언트가 모아 두었다가 다시 보내야 해요
* 브라우저에서 직접 연결. 브라우저 WebSocket API는 `Authorization` 헤더를 보낼 수 없으니 서버나 네이티브 앱에서 연결하세요

## 사용량은 어떻게 기록되나요?

Tiro는 세션마다 받은 오디오 길이와 연결 시간을 기록해요. 받은 오디오 길이는 세션 조회 응답과 `session.ended` 메시지의 `audioDurationMs`로 확인해요. 이 사용량은 노트 녹음 사용량이나 워크스페이스 사용 한도에 더하지 않아요. 요금은 엔터프라이즈 계약에서 정해요.

## 다음 단계

> [card] [빠른 시작](https://docs.tiro.ooo/ko/developers/realtime-transcription/quickstart.md)
>
> 세션을 만들고 오디오 파일을 보내 결과를 받아 보세요.

> [card] [WebSocket 프로토콜](https://docs.tiro.ooo/ko/developers/realtime-transcription/protocol.md)
>
> 메시지 필드, 재접속, 에러와 close code를 확인하세요.

Enterprise Plan

이 기능은 엔터프라이즈 플랜에서 제공돼요.  조직에 필요한 보안 구성을 영업팀이 함께 설계해 드려요.

[도입 문의하기](https://tiro.ax/ko/contact?utm_source=docs\&utm_medium=plan_callout\&utm_campaign=plan_upsell_enterprise\&utm_content=developers-realtime-transcription-overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.