scribe

Zoom AI Services Scribe

Zoom AI Services Scribe の背景情報。対象となる機能：

• 同期的な単一ファイルの文字起こし（POST /aiservices/scribe/transcribe）
• 非同期のバッチジョブ（/aiservices/scribe/jobs*）
• 短いファイルを繰り返しアップロードする、ブラウザーのマイクを使った擬似ストリーミング
• Webhook によるバッチステータスの更新
• Build プラットフォームの JWT 生成と認証情報の取り扱い

公式ドキュメント：

• https://developers.zoom.us/docs/ai-services/
• https://developers.zoom.us/docs/ai-services/scribe/
• https://developers.zoom.us/docs/api/ai-services/
• https://developers.zoom.us/api-hub/ai-services/methods/endpoints.json
• クイックスタートのサンプル：https://github.com/zoom/scribe-quickstart/

ルーティングのガードレール

• アップロード済みまたは保存済みのメディアをテキストに文字起こしする必要がある場合は、まずこちらにルーティングしてください。
• ファイルベースのアップロードやバッチジョブを使わずにライブ会議のメディアを処理する必要がある場合は、../rtms/SKILL.md にルーティングしてください。
• AI Services のパスに関するZoom REST API の一覧が必要な場合は、../rest-api/SKILL.md も組み合わせてください。
• Webhook の署名パターンや、汎用 HMAC レシーバーの堅牢化が必要な場合は、必要に応じて ../webhooks/SKILL.md も組み合わせてください。

クイックリンク

1. concepts/auth-and-processing-modes.md
2. scenarios/high-level-scenarios.md
3. examples/fast-mode-node.md
4. examples/batch-webhook-pipeline.md
5. references/api-reference.md
6. references/environment-variables.md
7. references/samples-validation.md
8. references/versioning-and-drift.md
9. troubleshooting/common-drift-and-breaks.md
10. RUNBOOK.md

基本的なワークフロー

1. Build プラットフォームの認証情報を取得し、HS256 JWT を生成します。
2. 短いファイル 1 つには高速モード、保存済みのアーカイブや大量のファイルにはバッチモードを選択します。
3. 文字起こしリクエストを送信します。
4. バッチジョブの場合は、ジョブ／ファイルのステータスをポーリングするか、Webhook 通知を受信します。
5. 文字起こし結果の JSON を保存して後処理します。

ホスト型の高速モードに関するガードレール

• 高速モード API の正式な制限は 100 MB および 2 hours ですが、ホスト型のブラウザーフローでは、上流からの応答が返る前にタイムアウトする場合があります。
• 現在のデプロイ済みサンプルでの観測結果：
  • 約 17.2 MB の MP4 は約 26s で完了
  • 約 38.6 MB の MP4 は約 26-37s で完了
  • 約 59.2 MB の MP4 はバックエンドで約 32-34s で完了
  • 約 59.2 MB のブラウザーリクエストの一部では、バックエンドのログに後から 200 が記録された一方、フロントエンドでは 504 が返された
• フロントエンドの 504 とバックエンドの 200 の組み合わせは、文字起こしが失敗したと即断せず、ブラウザー／エッジのタイムアウト競合として扱ってください。
• ホスト型 UI では、上流からの応答を待つ間ブラウザーを開き続けるのではなく、高速モード用の非同期リクエスト／ポーリングのラッパーを使用してください。
• ファイルが正式な高速モードのサイズ制限内であっても、サイズが大きい、または処理時間の予測が難しいメディアには、バッチモードを推奨します。

ブラウザーマイクのパターン

• scribe には、ドキュメント化されたリアルタイムストリーミング API サーフェスはありません。
• ブラウザーでマイクを使う場合は、疑似ストリーミングを使用してください。
  1. マイクの音声を短いチャンクに分けてキャプチャする
  2. 非同期の高速モードラッパーを通じて各チャンクをアップロードする
  3. 完了するまでポーリングする
  4. チャンクの文字起こし結果を順番に追加する
• 推奨される開始時の設定：
  • チャンクサイズ：5 seconds
  • 許容範囲：5-10 seconds
  • 同時に処理中のチャンクリクエスト数：2-3
• これは文字起こし結果を段階的に更新する実用的な UI パターンであり、rtms の代わりにはなりません。
• これは本番環境で推奨されるアーキテクチャではなく、フォールバック用のデモパターンとして扱ってください。
• アップロードが繰り返されることによるオーバーヘッド、チャンク境界のずれ、ブラウザーのコーデックやコンテナーのばらつき、文字起こし結果の結合の複雑さが生じます。
• 実際のライブストリーム取り込み、低遅延の連続メディア、またはサーバープッシュによるメディア転送が必要な場合は、代わりに ../rtms/SKILL.md を案内してください。

エンドポイント一覧

モード	メソッド	パス	用途
高速	POST	/aiservices/scribe/transcribe	1 ファイルの同期文字起こし
バッチ	POST	/aiservices/scribe/jobs	非同期バッチジョブの送信
バッチ	GET	/aiservices/scribe/jobs	ジョブの一覧表示
バッチ	GET	/aiservices/scribe/jobs/{jobId}	ジョブの概要と状態の確認
バッチ	DELETE	/aiservices/scribe/jobs/{jobId}	キュー待ちまたは処理中のジョブのキャンセル
バッチ	GET	/aiservices/scribe/jobs/{jobId}/files	ファイルごとの結果の確認

主なシナリオ

• ユーザーが録音を 1 件アップロードした後、必要に応じてクリップを文字起こしする。
• 保存済みの S3 通話アーカイブをバッチで文字起こしする。
• 文字起こし結果をデータベースや検索インデックスに書き込む、Webhook 駆動の ETL パイプライン。
• Zoom が管理する録画をエクスポートして独自のストレージに保存した後、再度文字起こしする。
• タイムスタンプ、チャンネル分離、話者のヒントが必要な、オフラインのコンプライアンスまたは QA ワークフロー。

連携

• 保存済みの Zoom 録画 -> ../rest-api/SKILL.md + scribe
• Webhook 検証の強化 -> ../webhooks/SKILL.md
• リアルタイムのライブ文字起こし／メディア -> ../rtms/SKILL.md
• 複数製品にまたがるルーティング -> ../general/SKILL.md

運用

• RUNBOOK.md - 5 分間の事前確認とデバッグのチェックリスト。