> ## 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キーはお客様のサーバーにだけ置き、クライアントにはセッションごとに発行される `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キー)
    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キーでセッションを作成し、`wsUrl` と `streamToken` を受け取ります | [APIリファレンス](https://docs.tiro.ooo/api-reference/realtime-transcription/create-realtime-transcription.md) |
| 2. 接続する | クライアントが `streamToken` を `Authorization` ヘッダーに入れて `wsUrl` に接続します | [接続](https://docs.tiro.ooo/ja/developers/realtime-transcription/protocol.md#handshake) |
| 3. 音声を送って結果を受け取る | 16 kHzモノラルのPCMを送り、`transcript` と `translation` メッセージを受け取ります | [メッセージ](https://docs.tiro.ooo/ja/developers/realtime-transcription/protocol.md#messages) |
| 4. 終了する | `session.end` を送ると、Tiroが残りの結果を送ってセッションを閉じます | [終了](https://docs.tiro.ooo/ja/developers/realtime-transcription/protocol.md#ending) |

接続が切れても、セッションが開いていれば同じトークンで再接続して続けられます。ルールは[再接続](https://docs.tiro.ooo/ja/developers/realtime-transcription/protocol.md#reconnect)にまとめています。

## 誰が使えますか？

次の3つの条件をすべて満たすとセッションを作成できます。

| 条件 | 満たさない場合 |
| - | - |
| エンタープライズプランの契約があり、Tiroがワークスペースでリアルタイム文字起こしAPIを有効にしていること。ご利用の際は下のお問い合わせボタンからご連絡ください | `403` `realtime_api_not_enabled` |
| ワークスペースに紐づいたAPIキーを使うこと。ワークスペースのAPIキー、またはワークスペースに紐づいたアカウントのAPIキーが該当します。アカウントのAPIキーの場合、キーの所有者がそのワークスペースのメンバーである必要があります | `403` `workspace_bound_key_required` または `workspace_access_denied` |
| スコープを指定したキーの場合、必要なスコープがあること。セッションの作成と終了には `realtime_transcription:write`、取得と一覧には `realtime_transcription:read` が必要です。`write` は `read` を含みます | `403` `insufficient_scope` |

組織のAPIキーとOAuthアクセストークンではこのAPIを呼び出せません。スコープは[認証](https://docs.tiro.ooo/ja/developers/fundamentals/authentication.md)で詳しく説明しています。

## どのような制限がありますか？

| 項目 | 値 | 超えた場合 |
| - | - | - |
| 同時セッション | ワークスペースあたり `OPEN` セッション10件。APIキーやユーザーを区別せずに数えます | セッション作成が `409` `concurrent_transcription_limit` で失敗します |
| 音声なし | 15分。セッション作成時刻または最後の音声フレームから数えます | セッションが `IDLE_TIMEOUT` で終了します |
| セッションの最大長 | 3時間。最初の接続から数え、切断中の時間も含みます | セッションが `MAX_DURATION` で終了します |
| 音声形式 | 16,000 Hz、モノラル、signed 16-bit little-endian PCM | 奇数バイトのフレームを受け取るとTiroが接続を閉じます |
| 音声フレームサイズ | 最大6,400バイト（200 ms）。3,200バイト（100 ms）を推奨します | Tiroが接続を閉じます |
| 音声の先行量 | 実際の経過時間より最大60秒先まで送れます | Tiroがclose `4029` で接続を閉じます。待ってから再接続してください |
| REST呼び出し | APIキーあたり60秒間に600回 | `429` と `Retry-After` が返ります |

> [!WARNING]
>
> 使い終わったら `session.end` を送るか `POST /v1/external/realtime-transcriptions/{id}/end` を呼び出してください。WebSocket接続を閉じるだけでは、セッションは `OPEN` のまま残ります。音声なしで15分経って自動で終了するまで同時セッションの枠を1つ占有し、整理がさらに最大3分ほど遅れることがあります。

## どの言語に対応していますか？

文字起こしと翻訳はどちらも、[対応ロケール](https://docs.tiro.ooo/ja/developers/fundamentals/supported-locales.md)の17ロケールに対応しています。セッション作成時に `transcriptionLocale` を省略するか `AUTO` を送ると、Tiroが話されている言語を自動で検出します。`translationLocale` は1つだけ指定でき、自動検出は使えません。

翻訳は原文の文と1対1で対応しません。翻訳の断片は届いた順につなげて表示してください。ルールは[`translation` メッセージ](https://docs.tiro.ooo/ja/developers/realtime-transcription/protocol#translation)にまとめています。

## このAPIが提供しないものは何ですか？

現在のバージョンは次の機能を提供しません。

* 話者の区別、単語や文単位のタイムスタンプ
* ノートの作成とWebhook
* 音声の保存と再送。切断中の音声はクライアントがためておき、再送する必要があります
* ブラウザからの直接接続。ブラウザのWebSocket APIは `Authorization` ヘッダーを送れないため、サーバーまたはネイティブアプリから接続してください

## 利用量はどのように記録されますか？

Tiroはセッションごとに、受け取った音声の長さと接続時間を記録します。受け取った音声の長さは、セッション取得のレスポンスと `session.ended` メッセージの `audioDurationMs` で確認できます。この利用量は、ノートの録音利用量やワークスペースの利用上限には加算されません。料金はエンタープライズ契約で定めます。

## 次のステップ

> [card] [クイックスタート](https://docs.tiro.ooo/ja/developers/realtime-transcription/quickstart.md)
>
> セッションを作成し、音声ファイルを送って結果を受け取ってみましょう。

> [card] [WebSocketプロトコル](https://docs.tiro.ooo/ja/developers/realtime-transcription/protocol.md)
>
> メッセージのフィールド、再接続、エラーとclose codeを確認できます。

Enterprise Plan

この機能はエンタープライズプランでご利用いただけます。  組織に必要なセキュリティ構成を営業チームがご支援します。

[導入のお問い合わせ](https://tiro.ax/ja/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.