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を選びます。ファイルは 25 MB 未満に制限 — 大きなファイルは分割してください。promptで語彙やスタイルを誘導できます。gpt-4o-transcribe系モデルではstream: trueによるストリーミング出力も可能です。
<critical_requirements>
重要: スキル使用前の注意点
すべてのコードは CLAUDE.md のプロジェクト規約に従うこと(kebab-case、名前付きエクスポート、import 順序、
import type、名前付き定数)
(ユースケースに適したモデルを必ず選択すること — gpt-4o-transcribe は精度、whisper-1 はタイムスタンプ/SRT/VTT 出力、gpt-4o-transcribe-diarize は話者ラベル向け)
(25 MB を超える音声ファイルは 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は話者識別を追加。 - ファイルサイズが主要な制約 — 25 MB 制限により、長い音声は分割が必要。文の境界で分割してコンテキストを保持。
- プロンプトで精度向上 —
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: 大きなファイルのチャンク分割
25 MB を超える音声ファイルは転写前に分割する必要があります。コンテキストを保持するために、文の境界(例: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: ストリーミング転写
モデルが音声を処理する際に、部分的な転写結果をストリーミングします。gpt-4o-transcribe と gpt-4o-mini-transcribe のみが stream: true をサポートします。段階的出力には 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(2~10 秒の音声クリップをデータ URL として)を指定すると、セグメントを既知の話者(最大 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"
+-- 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>
注意すべきポイント
高優先度の問題:
response_format: "verbose_json"なしでwhisper-1でtimestamp_granularitiesを使用(静かに無視される)- 25 MB を超えるファイルを送信(API がエラーを返す)
- 30 秒以上の音声で
chunking_strategyなしでgpt-4o-transcribe-diarizeを使用(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がプロンプトや logprobs をサポートすることを期待(サポートしません)- 英語音声に翻訳エンドポイントを使用(非英語から英語への翻訳のみ)
- 分割ファイルの転写時に前のチャンクのコンテキストを提供しない(境界での精度が低下)
落とし穴とエッジケース:
promptパラメータはwhisper-1で約 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は話者を「A」「B」「C」とラベル付けします。known_speaker_namesとknown_speaker_references(短い音声クリップ)を提供しない限りこの方式です。- 翻訳エンドポイントは
whisper-1のみをサポートし、英語のみを出力します — この API で他の言語に翻訳する方法はありません。 - ストリーミング転写は
transcript.text.deltaイベント(delta文字列プロパティ付き)と、最後にtranscript.text.doneイベントを発行します。
</red_flags>
<critical_reminders>
重要な注意点
**
…
[翻訳のため省略] </critical_reminders>