> ## 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.

# 概要

> ワークスペースに紐づくAPIキーを使い、Voice File Jobの作成、音声のアップロード、文字起こし結果の取得と削除までの流れを説明します。

このページでは、Voice File Job の作成、音声のアップロード、結果の取得までのエンドツーエンドの流れを説明します。現在の実装では、クライアントからアップロード完了を通知する方式（S3 イベントは使用しません）を採用しています。

## 必要なもの

* ワークスペースに紐づくユーザーキーまたはワークスペースシステムキー: `Authorization: Bearer {id}.{secret}`
* Tiroの管理者が対象ワークスペースのVoice File Jobポリシーを有効にしていること
* transcriptLocaleHints: 最大 1 つ（任意）
  * **指定しない場合、言語は自動的に検出されます**
* translationLocales: 最大 5 つ（任意）

## エンドツーエンドのチェックリスト

1. ジョブを作成 → `{ id, uploadUri }` を受け取る
2. 音声を `uploadUri` にアップロード
3. `PUT /v1/external/voice-file/jobs/{jobId}/upload-complete` を呼び出す
4. ジョブのステータスを完了までポーリング
5. transcript と（任意で）translations を取得
6. コンテンツをより深く理解するために paragraph summary を取得

## Webhookで状態の変更を受け取り、ジョブを削除するにはどうすればよいですか？

ポーリングを使わずにジョブの状態変更を受け取るには、`voice_file_job.created`、`voice_file_job.completed`、`voice_file_job.failed`、`voice_file_job.deleted`を購読してください。Webhookのペイロードにはジョブのメタデータのみが含まれ、文字起こし本文は含まれません。文字起こし本文は`GET /v1/external/voice-file/jobs/{jobId}/transcript`で取得してください。

どの状態のジョブでも`DELETE /v1/external/voice-file/jobs/{jobId}`で削除できます。Tiroは音声と生成済みの結果を削除し、削除後に届いた処理コールバックは無視します。

## 音声と文字起こしデータはどのように保管されますか？

アップロードした音声はTiroが管理するオブジェクトストレージに、文字起こしと翻訳の結果はTiroのサービスデータベースに保存されます。APIには自動保管期間を設定する機能がないため、データが不要になったら`DELETE /v1/external/voice-file/jobs/{jobId}`を呼び出してください。

ワークスペースのユーザーキーは、同じワークスペースでそのユーザーが作成したジョブにアクセスできます。ワークスペースシステムキーは、同じワークスペースのジョブにアクセスできます。ジョブを削除すると、Tiroはアップロードした音声、文字起こし、翻訳結果を削除します。削除したジョブはAPIから取得できません。

## ポーリング戦略（推奨）

* `GET /v1/external/voice-file/jobs/{jobId}` を指数バックオフでポーリングします
  * 1〜2 秒間隔から始め、4 秒、8 秒と増やし、最大 30 秒まで
  * 停止条件:
    * 成功: `status` = `COMPLETED`
    * 失敗: `status` = `FAILED`
  * 成功後:
    * 必ず transcript を取得: `GET /v1/external/voice-file/jobs/{jobId}/transcript`
    * translations をリクエストした場合: `GET /v1/external/voice-file/jobs/{jobId}/translations` またはロケール別のエンドポイント
    * paragraph summary を取得:
      * transcript の場合: `GET /v1/external/voice-file/jobs/{jobId}/transcript/paragraph-summary`
      * translations の場合: `GET /v1/external/voice-file/jobs/{jobId}/translations/{locale}/paragraph-summary`

<Note>
  処理が正常に完了した場合の最終ステータスは `COMPLETED` です。これは、transcript、translation（リクエストした場合）、およびその両方の paragraph summary を含む、すべての処理が完了したことを意味します。
</Note>

## ファイルの制限と要件

### サポートされる音声フォーマット

業界標準の STT 機能に基づき、Tiro は以下のフォーマットをサポートしています。

**音声フォーマット:**

| Format  | MIME Type  | Extension |
| ------- | ---------- | --------- |
| **MP3** | audio/mpeg | .mp3      |
| **WAV** | audio/wav  | .wav      |
| **M4A** | audio/mp4  | .m4a      |

**動画フォーマット（音声抽出）:**

| Format  | MIME Type | Extension |
| ------- | --------- | --------- |
| **MP4** | video/mp4 | .mp4      |

### ファイルサイズと長さの制限

| 制限の種類         | 値           | 備考                    |
| ------------- | ----------- | --------------------- |
| **最大ファイルサイズ** | 500 MB      | ほとんどのユースケースで十分な実用的な上限 |
| **最大の長さ**     | 4 時間        | ほとんどの会議やインタビューをカバー    |
| **最小サンプルレート** | 8 kHz       | 音声認識の最小値              |
| **推奨サンプルレート** | 16 kHz+     | 精度に最適                 |
| **最大サンプルレート** | 48 kHz      | スタジオ品質に対応             |
| **チャンネル**     | モノラルまたはステレオ | 複数話者に対応               |

### 処理時間の目安

処理時間は、長いファイルに対する並列処理によって最適化されています。

| ファイルの長さ | 一般的な処理時間 |
| ------- | -------- |
| 5 分未満   | 45〜75 秒  |
| 5〜20 分  | 1〜3 分    |
| 20〜60 分 | 3〜6 分    |
| 1〜4 時間  | 6〜18 分   |

## Paragraph Summary 機能

Paragraph Summary 機能は、音声コンテンツのインテリジェントな要約を提供し、transcript や translation を段落単位の理解しやすい要約に分割します。

### 仕組み

1. **Transcript の処理**: 文字起こしが完了すると、CompositeTextSplitter を使ってテキストが自動的に論理的な段落に分割されます
2. **要約の生成**: 各段落は ParagraphSummarizer を通して処理され、簡潔な要約が作成されます
3. **Translation との統合**: translations がリクエストされた場合、各ロケールについて、翻訳されたコンテンツに基づいて要約が再生成されます
4. **非同期処理**: 要約の生成は、transcript / translation の完了後に非同期で行われます

## シーケンス

```mermaid theme={"system"}
sequenceDiagram
    participant Client
    participant API as Tiro API
    participant Storage as File Storage
    participant Worker as Tiro Worker
    participant STT as STT Engine
    participant TR as Translation Engine
    participant WH as Webhook Service

    %% Job creation
    Client->>API: POST /v1/external/voice-file/jobs (transcriptLocaleHints, translationLocales)
    API->>Storage: Generate upload URL
    API-->>Client: 201 Created {id, uploadUri}

    %% File upload
    Client->>Storage: PUT audio file
    Client->>API: PUT /v1/external/voice-file/jobs/{jobId}/upload-complete

    %% Pipeline
    API->>Worker: Enqueue job (start processing)
    Worker->>STT: Speech-to-text
    STT-->>Worker: transcript
    alt translations requested
        Worker->>TR: Translate to requested locales
        TR-->>Worker: translations
    end
    Worker->>API: mark job = COMPLETED or FAILED
    opt Webhook configured
        API-->>WH: POST {jobId, status=COMPLETED}
    end

    %% Results
    Client->>API: GET /v1/external/voice-file/jobs/{jobId}
    API-->>Client: status, timestamps
    Client->>API: GET /v1/external/voice-file/jobs/{jobId}/transcript
    API-->>Client: transcript
    Client->>API: GET /v1/external/voice-file/jobs/{jobId}/translations
    API-->>Client: translations[]
```

試してみる準備はできましたか？ [ステップバイステップ・チュートリアル](/en/developers/voice-file/tutorial) で、アップロードからポーリング、そして最初の transcript の取得まで、一連の流れを最後まで体験できます。