Skip to main content
このページでは、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
処理が正常に完了した場合の最終ステータスは COMPLETED です。これは、transcript、translation（リクエストした場合）、およびその両方の paragraph summary を含む、すべての処理が完了したことを意味します。

​
ファイルの制限と要件

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

業界標準の STT 機能に基づき、Tiro は以下のフォーマットをサポートしています。 音声フォーマット: 動画フォーマット（音声抽出）:

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

​
処理時間の目安

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

​
Paragraph Summary 機能

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

​
仕組み

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

​
シーケンス

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