音声認識 APIで、音声・動画ファイルをアプリに取り込みます

multipartのfileにファイル本体を指定します。language、diarize、source、webhook_urlもフォームフィールドで渡せます。送信例と、完了を受け取るWebhookを確認してください。

HTTPクライアントにmultipartのboundaryを設定させます。JSONにローカルのパスを書くだけでは送信できません。必要なのは実際のファイルのバイト列です。空のファイルや未対応の拡張子は、送信前に確認してください。同じ内容を再送しても解決しません。

送信方法はバイト数で選び、録音の長さは別に確認します。圧縮した録音は95MB未満でも5時間を超えることがあります。反対に、高画質の短い動画は95MBを超え、分割アップロードが必要になることがあります。

ファイル名とサイズを指定すると、送信するチャンクの一覧と、そのアップロード専用のX-Upload-Tokenが返ります。手順全体は分割アップロードにまとめています。

チャンクの位置とサイズは、返ってきた一覧に従います。指定されたオフセットから指定バイト数を読み出し、最後のチャンクだけ短くなる場合も、そのサイズで送ります。トークンはバイナリのPUTリクエストに使います。有効期間は1時間で、他のアップロードや通常のAPI操作には使えません。

予約を再試行する可能性がある場合は、同じIdempotency-Keyを使います。トークンが切れたら、同じキーと同じパラメーターで予約リクエストを再送し、既存のアップロード用に新しいトークンを受け取ります。通信が切れるたびに新規予約を作る必要はありません。

各チャンクを指定URLにPUTし、すべて送ったら完了リクエストを送ります。チャンクの確認が済むと文字起こしがキューに入ります。アップロードAPIで進捗確認と完了処理を実装できます。

再開前にGET /v1/transcriptions/:id/uploadを呼び、received_chunksを元の一覧と照合します。不足分だけ送信してください。同じチャンクを再送すると置き換わりますが、本文のサイズは計画どおりである必要があります。401ならトークンの期限も確認します。

完了時に409 upload_incompleteが返ったら、示されたインデックスのチャンクを送ります。キューに入った後は文字起こしのステータスを確認するか、Webhookを待ちます。アプリの画面でも「アップロード中」と「文字起こし中」を分けて表示すると、進捗を正しく伝えられます。

awaiting_uploadはファイルを待っている状態で、文字起こしはまだ始まっていません。送信、チャンクの確認、メディアの処理の順に進みます。完了リクエスト後に接続が切れた場合も、まず既存のジョブを読み、現在の状態を確かめます。

チームごとに未完了のアップロード予約を20件まで持てます。24時間以内に完了しない予約はキャンセルされ、チャンクも削除されます。処理を終えたメディアは、その終了から24時間後に削除します。後で音声を再生するアプリでは、元のファイルを自分で保管してください。

利用者向けのアップロード画面なら録音の準備と確認、調査用の連携ならインタビューの整理方法も参考になります。ファイル送信の実装と、文字起こしを読み返すための設計は、それぞれ必要です。