概要

Voice File Job は、作成 → アップロード → upload-complete の呼び出し → ステータス確認 → 結果の取得の順に処理します。upload-complete はクライアントが直接呼び出し、S3 イベントは使用しません。

​

必要なもの

• アカウントのAPIキーまたはワークスペースのAPIキー: 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}を呼び出してください。 アカウントのAPIキーは自身が作成したジョブのみ、ワークスペースの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

​

ファイルの制限と要件

​

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

サポートするファイル形式は以下のとおりです。 音声フォーマット: 動画フォーマット（音声抽出）:

​

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

​

処理時間の目安

ファイルの長さごとの処理時間の目安は以下のとおりです。

​

Paragraph Summary 機能

Paragraph Summary は、文字起こしまたは翻訳の結果を段落ごとに要約します。

​

仕組み

文字起こしのテキストを段落に分割し、各段落の要約を作成します。翻訳をリクエストした場合は、翻訳結果にも同じ処理を適用します。要約は文字起こし・翻訳の処理が完了したあとに非同期で生成されます。

​

シーケンス

全体の例はステップバイステップ・チュートリアルを参照してください。