メインコンテンツへスキップ
Voice File Job APIはエンタープライズプランでご利用いただけます。個人プランおよびチームプランでは有効化できません。 Voice File Job は、作成 → アップロード → upload-complete の呼び出し → ステータス確認 → 結果の取得の順に処理します。upload-complete はクライアントが直接呼び出し、S3 イベントは使用しません。

​
必要なもの

  • アカウントのAPIキーまたはワークスペースのAPIキー: Authorization: Bearer {id}.{secret}
  • scope を指定したキーの場合、ジョブの作成・アップロード完了の通知・削除には voice_file_job:write、取得には voice_file_job:read が必要です。write は read を含み、scope を指定していないキーはすべての操作ができます。
  • エンタープライズプランの契約とともにVoice File Jobポリシーが有効化されたワークスペース
  • ワークスペースに紐づかないアカウントのAPIキーと組織のAPIキーは、ジョブの作成時に workspaceGuid を送信する必要があります
  • transcriptLocaleHints: 最大 1 つ（任意）
    • 指定しない場合、言語は自動的に検出されます
  • translationLocales: 最大 5 つ（任意）

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

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

​
ジョブの完了はどのように確認しますか？ Webhook（推奨）

ジョブの完了はWebhookで受け取る方法を推奨します。処理にはファイルの長さに応じて通常45秒〜18分かかり、キューの状況によってはさらに長くなることがあります。Webhookを購読すると、Tiroが処理を終えた時点でvoice_file_job.completedまたはvoice_file_job.failedイベントを送信するため、待機中にステータスを繰り返し取得する必要がありません。
  • voice_file_job.completedとvoice_file_job.failedを購読してください。ワークスペースWebhookはそのワークスペースで作成されたすべてのジョブのイベントを、組織Webhookは組織に属するすべてのワークスペースで作成されたジョブのイベントを受け取ります。ノートと異なり、フォルダの共有範囲は適用されません。ユーザー Webhookは、本人がアカウントAPI Keyで作成したジョブのうち、Webhookを登録したワークスペースで作成したジョブのイベントのみを受け取ります。登録方法はWebhook の概要をご覧ください。
  • イベントのdata.resourceIdがジョブID、data.resource.statusがCOMPLETEDまたはFAILEDです。すべてのフィールドはEvent Structureで確認できます。
  • Webhookのペイロードにはジョブのメタデータのみが含まれ、文字起こし本文は含まれません。文字起こし本文はGET /v1/external/voice-file/jobs/{jobId}/transcriptで取得してください。
  • Webhookの配信がリトライを含めてすべて失敗した場合、Tiroはそのイベントを再送しません。想定される処理時間を過ぎてもイベントが届かないジョブは、GET /v1/external/voice-file/jobs/{jobId}でステータスを確認してください。
ジョブの作成と削除を追跡するには、voice_file_job.createdとvoice_file_job.deletedも購読できます。

​
ポーリング戦略（Webhookを受け取れない場合）

Webhookのエンドポイントを運用できない場合や、Webhookイベントが届かない場合は、ジョブのステータスをポーリングしてください。
  • 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 を含む、すべての処理が完了したことを意味します。

​
ジョブがFAILEDでも文字起こしを取得できますか？

取得できる場合があります。要約の生成だけが失敗した場合も、ジョブはFAILEDになります。このときGET /v1/external/voice-file/jobs/{jobId}のレスポンスのtranscriptAvailableがtrueであれば、GET /v1/external/voice-file/jobs/{jobId}/transcriptで文字起こしを取得できます。 失敗の理由はerrorMessageに入っています。voice_file_job.failedのWebhookのdata.resource.errorMessageにも同じ値が入っています。

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

アップロードした音声はTiroが管理するオブジェクトストレージに、文字起こしと翻訳の結果はTiroのサービスデータベースに保存されます。APIには自動保管期間を設定する機能がないため、データが不要になったらDELETE /v1/external/voice-file/jobs/{jobId}を呼び出してください。 どの状態のジョブでもDELETE /v1/external/voice-file/jobs/{jobId}で削除できます。Tiroは音声と生成済みの結果を削除し、削除後に届いた処理コールバックは無視します。 アカウントのAPIキーは自身が作成したジョブのみ、ワークスペースのAPIキーは同じワークスペースのすべてのジョブにアクセスできます。ジョブを削除すると音声と文字起こし・翻訳結果も消去され、再度取得することはできません。

​
ファイルの制限と要件

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

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

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

​
処理時間の目安

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

​
Paragraph Summary 機能

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

​
仕組み

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

​
シーケンス

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