OpenAI Whisper パターン
クイックガイド: 音声認識には
client.audio.transcriptions.create()、非英語音声を英語テキストに翻訳するにはclient.audio.translations.create()を使用します。最高精度にはgpt-4o-transcribe、コスト効率にはgpt-4o-mini-transcribe、タイムスタンプ/SRT/VTTにはwhisper-1、話者識別にはgpt-4o-transcribe-diarizeを選択します。ファイルは25MB未満である必要があります。大きなファイルは分割してください。promptを使用して語彙やスタイルを誘導します。gpt-4o-transcribeモデルではstream: trueによるストリーミング出力が可能です。
<critical_requirements>
重要: このスキルを使用する前に
すべてのコードは CLAUDE.md のプロジェクト規約に従う必要があります(ケバブケース、名前付きエクスポート、インポート順序、
import type、名前付き定数)
(ユースケースに適したモデルを選択する必要があります -- 精度重視なら gpt-4o-transcribe、タイムスタンプ/SRT/VTT出力なら whisper-1、話者ラベルが必要なら gpt-4o-transcribe-diarize)
(25MBを超える音声ファイルは、APIに送信する前に分割する必要があります -- APIはこの制限を超えるファイルを拒否します)
(timestamp_granularities を使用する場合、response_format: "verbose_json" を渡す必要があります -- タイムスタンプは whisper-1 でのみこの形式で機能します)
(30秒を超える音声で gpt-4o-transcribe-diarize を使用する場合、chunking_strategy: "auto" を設定する必要があります -- APIで必須です)
</critical_requirements>
自動検出: Whisper, whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize, audio.transcriptions, audio.translations, transcription, speech-to-text, diarization, diarized_json, timestamp_granularities, verbose_json
使用すべき場合:
- 音声ファイル(会議、インタビュー、ポッドキャスト、ボイスメモ)のテキストへの文字起こし
- 非英語音声を英語テキストに翻訳
- 音声からSRTまたはVTT形式の字幕を生成
- 動画編集のためのワードレベルまたはセグメントレベルのタイムスタンプ取得
- 複数話者の音声における話者の識別(話者分離)
- モデルが音声を処理する際に、結果を段階的にストリーミング出力
カバーされる主要パターン:
- モデル選択(whisper-1 vs gpt-4o-transcribe vs gpt-4o-mini-transcribe vs gpt-4o-transcribe-diarize)
- レスポンス形式(json, text, srt, vtt, verbose_json, diarized_json)
- タイムスタンプ(ワードレベル、セグメントレベル)と字幕生成
- 語彙、略語、スタイルのためのプロンプティング
- 大きなファイル(> 25 MB)のコンテキストを保持した分割処理
stream: trueによるストリーミング文字起こしaudio.translations.create()による英語への翻訳- 話者参照を用いた話者分離
使用すべきでない場合:
- テキストから音声への変換(TTS) -- OpenAI TTS API(
client.audio.speech.create())を使用します - リアルタイム双方向音声会話 -- OpenAI Realtime API を使用します
- OpenAI以外のプロバイダーによる文字起こし -- プロバイダーに依存しない音声SDKを使用します
サンプル一覧
- コア: 文字起こし、翻訳、タイムスタンプ、チャンキング、ストリーミング、話者分離 -- すべての音声APIパターン
哲学
OpenAI Audio API は、さまざまなニーズに最適化された複数のモデルを通じて、音声からテキストへの文字起こしと翻訳を提供します。APIはシンプルで、音声ファイルを送信してテキストを受け取りますが、適切なモデル、レスポンス形式、パラメータを選択することが高品質な結果を得るために重要です。
基本原則:
- モデル選択が重要 --
gpt-4o-transcribeは最高精度で、幻覚率が低くなります。whisper-1は、SRT/VTT/verbose_json(タイムスタンプ付き)をサポートする唯一のモデルです。gpt-4o-transcribe-diarizeは話者識別を追加します。 - ファイルサイズが主要な制約 -- 25MBの制限があるため、長い音声は分割する必要があります。コンテキストを維持するために、文の境界で分割します。
- プロンプティングで精度が向上 --
promptパラメータは、語彙、略語、書式スタイルを誘導します。指示を与えるものではなく、モデルが照合するコンテキストを提供します。 - レスポンス形式で利用可能な機能が決まる -- タイムスタンプには
whisper-1でverbose_jsonが必要です。話者分離にはdiarized_jsonが必要です。SRT/VTTはwhisper-1のみで利用可能です。
Audio API を使用すべき場合:
- 録音された音声ファイルの正確な文字起こしが必要な場合
- 音声から字幕(SRT/VTT)が必要な場合
- 会話の中で誰が話しているかを識別する必要がある場合
- 非英語の音声を英語テキストに翻訳する必要がある場合
使用すべきでない場合:
- リアルタイム音声チャット -- 代わりに Realtime API を使用します
- テキストから音声への変換 --
client.audio.speech.create()を使用します - 英語以外のターゲット言語での文字起こしが必要な場合(翻訳は英語のみを出力します)
コアパターン
パターン1: 基本的な文字起こし
音声ファイルを送信してテキストを受け取ります。モデルは言語を自動検出します。
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
});
最高精度には gpt-4o-transcribe を使用します。プレーンテキストのみが必要な場合に whisper-1 と verbose_json を使用しないでください。オーバーヘッドが追加され、幻覚率が高くなります。完全な例については core.md を参照してください。
パターン2: モデル選択
各モデルには、明確な機能とトレードオフがあります。
何が必要ですか?
+-- 最高精度、プレーンテキスト -> gpt-4o-transcribe
+-- コスト効率、プレーンテキスト -> gpt-4o-mini-transcribe
+-- タイムスタンプ(ワード/セグメント) -> whisper-1 (verbose_json)
+-- SRTまたはVTT字幕 -> whisper-1 (srt/vtt形式)
+-- 話者識別 -> gpt-4o-transcribe-diarize
+-- ストリーミング出力 -> gpt-4o-transcribe または gpt-4o-mini-transcribe
モデル機能マトリックス
| 機能 | whisper-1 | gpt-4o-transcribe | gpt-4o-mini-transcribe | gpt-4o-transcribe-diarize |
|---|---|---|---|---|
| レスポンス形式 | json, text, srt, vtt, verbose_json | json, text | json, text | json, text, diarized_json |
| タイムスタンプ | ワード + セグメント | なし | なし | なし |
| ストリーミング | なし | あり | あり | なし |
| プロンプトサポート | あり (224 トークン) | あり | あり | なし |
| Logprobs | なし | あり | あり | なし |
| 話者ラベル | なし | なし | なし | あり |
| 言語パラメータ | あり | あり | あり | あり |
パターン3: 語彙とスタイルのためのプロンプティング
prompt パラメータはコンテキストを提供します。指示ではありません。名前、略語、書式スタイルのスペルを誘導します。「注意して文字起こししてください」のような指示を出すために使用しないでください。スタイルと語彙のコンテキストを照合します。
const VOCABULARY_PROMPT = "Kubernetes, kubectl, etcd, NGINX, gRPC, PostgreSQL";
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
prompt: VOCABULARY_PROMPT,
});
使用例: 略語/固有名詞、チャンク間のコンテキスト保持(前のトランスクリプトの末尾を渡す)、フィラーワードの維持、ライティングスタイルのガイド。詳細な語彙例については core.md を参照してください。
パターン4: 大きなファイルのチャンキング(分割処理)
25MBを超える音声ファイルは、文字起こしの前に分割する必要があります。コンテキストを維持するために、文の境界(例: ffmpegを使用)で分割します。チャンク間の連続性を保つために、前のトランスクリプトの末尾を prompt として渡します。
const MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024; // 25 MB
// ffmpegで分割: ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3
// その後、前のコンテキストをpromptで渡しながら順次文字起こし
サイズ検証とコンテキスト保持を含む完全なチャンキング実装については、core.md を参照してください。
パターン5: ストリーミング文字起こし
モデルが音声を処理する際に、部分的な文字起こし結果をストリーミング出力します。stream: true をサポートするのは gpt-4o-transcribe と gpt-4o-mini-transcribe のみです。プログレッシブ出力には transcript.text.delta イベント、完了時には transcript.text.done イベントをリッスンします。whisper-1 で stream: true を使用しないでください。サポートされていません。
const stream = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
stream: true,
});
for await (const event of stream) {
if (event.type === "transcript.text.delta") process.stdout.write(event.delta);
}
完全なストリーミングとlogprobの例については、core.md を参照してください。
パターン6: 英語への翻訳
非英語音声を英語テキストに翻訳します。audio.translations.create() 経由でサポートされるのは whisper-1 のみです。同じ言語への文字起こしには、代わりに audio.transcriptions.create() を使用します。翻訳は英語のみを出力します。他の言語に翻訳する方法はありません。
const translation = await client.audio.translations.create({
model: "whisper-1",
file: createReadStream(audioPath),
});
語彙プロンプティングを含む完全な翻訳例については、core.md を参照してください。
パターン7: 話者分離(話者ダイアリゼーション)
複数話者の音声で誰が話しているかを識別します。gpt-4o-transcribe-diarize を response_format: "diarized_json" および chunking_strategy: "auto"(30秒以上の音声で必須)とともに使用します。話者分離は prompt、logprobs、timestamp_granularities をサポートしていません。
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe-diarize",
file: createReadStream(audioPath),
response_format: "diarized_json",
chunking_strategy: "auto",
});
オプションで、known_speaker_names と known_speaker_references(データURLとしての2~10秒の音声クリップ)を指定して、セグメントを既知の話者(最大4人)にマッピングできます。完全な話者分離例については core.md を参照してください。
<decision_framework>
決定フレームワーク
選択すべきモデル
文字起こしに何が必要ですか?
+-- 単にテキスト(最高精度) -> gpt-4o-transcribe
+-- 単にテキスト(コスト重視) -> gpt-4o-mini-transcribe
+-- ワード/セグメントタイムスタンプ -> whisper-1 (verbose_json)
+-- SRTまたはVTT字幕ファイル -> whisper-1 (srt または vtt)
+-- 話者識別 -> gpt-4o-transcribe-diarize
+-- プログレッシブ/ストリーミング出力 -> gpt-4o-transcribe (stream: true)
使用すべきレスポンス形式
どのような出力が必要ですか?
+-- プレーンテキスト文字列 -> "text"
+-- テキストフィールドを含むJSON -> "json"(デフォルト)
+-- 動画の字幕 -> "srt" または "vtt"(whisper-1のみ)
+-- タイムスタンプ(ワード/セグメント) -> "verbose_json"(whisper-1のみ)
+-- 話者ラベル付きセグメント -> "diarized_json"(gpt-4o-transcribe-diarizeのみ)
文字起こし vs 翻訳
音声は英語ですか?
+-- はい -> audio.transcriptions.create() を使用
+-- いいえ -> 元の言語で出力しますか?
+-- はい -> audio.transcriptions.create() を使用(言語を自動検出)
+-- いいえ(英語が必要) -> audio.translations.create() を使用(whisper-1のみ)
</decision_framework>
<red_flags>
レッドフラグ
高優先度の問題:
whisper-1でtimestamp_granularitiesをresponse_format: "verbose_json"なしで使用(サイレントに無視される)- 25MBを超えるファイルを送信(APIがエラーを返す)
- 30秒以上の音声で
gpt-4o-transcribe-diarizeをchunking_strategyなしで使用(APIがエラーを返す) whisper-1でstream: trueを使用(サポートされていない)
中優先度の問題:
gpt-4o-transcribeの方が高精度であるにもかかわらずwhisper-1を使用(whisper-1は幻覚率が高い)- 言語が分かっている場合に
languageパラメータを渡さない(短い音声やノイズの多い音声では自動検出が正しくない可能性がある) - 同じ言語への文字起こしをしたいのに
audio.translations.create()を使用(翻訳は常に英語を出力する) - チャンキング時に音声を文の途中で分割する(境界でコンテキストが失われる)
よくある間違い:
promptパラメータを指示(「注意して文字起こししてください」)として扱う -- 語彙とスタイルマッチングのためのコンテキストです- SRT/VTT出力が必要なのに
gpt-4o-transcribeを使用 -- それらの形式をサポートしているのはwhisper-1のみです gpt-4o-transcribe-diarizeがプロンプトやログプロブをサポートすると期待する(サポートしません)- 英語の音声に翻訳エンドポイントを使用する(非英語を英語にのみ翻訳します)
- 分割されたファイルを文字起こしする際に、前のチャンクのコンテキストを提供しない(境界での精度が低下する)
落とし穴とエッジケース:
whisper-1のpromptパラメータは約224トークンに制限されています。より長いプロンプトは切り詰められます。whisper-1は、無音または無音に近い音声セグメントに対してテキストを幻覚することがあります。これを検出するにはverbose_jsonのno_speech_probを使用します。gpt-4o-transcribeとgpt-4o-mini-transcribeはjsonとtextのレスポンス形式のみをサポートします。srt、vtt、verbose_jsonはサポートしません。languageパラメータはISO 639-1コード(例:"en"、"fr"、"ja")を使用します。設定すると、短い音声の精度が向上します。- サポートされているファイル形式: flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav、webm。その他の形式は事前に変換する必要があります。
gpt-4o-transcribe-diarizeは、known_speaker_namesとknown_speaker_references(短い音声クリップ)を提供しない限り、話者を "A"、"B"、"C" としてラベル付けします。- 翻訳エンドポイントは
whisper-1のみをサポートし、英語のみを出力します。このAPIを介して他の言語に翻訳する方法はありません。 - ストリーミング文字起こしは、
delta文字列プロパティを持つtranscript.text.deltaイベントと、最終的なtranscript.text.doneイベントを発行します。
</red_flags>
<critical_reminders>
重要なリマインダー
**
...
[翻訳のため省略]