Communitygithub.com

majiayu000/claude-skill-registry

透過 OpenAI Audio API 進行語音轉文字及翻譯——模型選擇、回應格式、時間戳記、提示、串流、分段與說話者辨識

claude-skill-registry 是什麼?

此技能提供了一套完整的 OpenAI Audio API 使用模式,主要涵蓋語音轉文字(Speech-to-Text)翻譯與英語化文本輸出。它詳細說明了不同模型(如 `gpt-4o-transcribe`、`whisper-1`、`gpt-4o-transcribe-diarize`)的選擇策略,並針對精確度、成本效率、時間戳記、字幕格式(SRT/VTT)與說話者辨識等需求,提供了明確的建議。技能中也強調了檔案大小限制(25 MB)的分段處理技巧,以及如何利用 `prompt` 參數來提升詞彙與風格的準確性。此外,還涵蓋了串流輸出與 API 的關鍵限制條件(如 `whisper-1` 不支援串流、`gpt-4o-transcribe-diarize` 需要特定回應格式等),協助開發者避免常見錯誤。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry/tree/HEAD/skills/ai-llm/api-ai-openai-whisper

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

OpenAI Whisper 模式

快速指南: 使用 client.audio.transcriptions.create() 進行語音轉文字,使用 client.audio.translations.create() 將非英語音訊轉換為英語文字。選擇 gpt-4o-transcribe 以獲得最高準確度,gpt-4o-mini-transcribe 以節省成本,whisper-1 以取得時間戳記/SRT/VTT,或 gpt-4o-transcribe-diarize 以進行說話者識別。檔案必須小於 25 MB——較大的檔案請進行分段。使用 prompt 來引導詞彙和風格。可透過 stream: true 在 gpt-4o-transcribe 模型上實現漸進式輸出的串流。


<critical_requirements>

關鍵:使用此技能前

所有程式碼必須遵循 CLAUDE.md 中的專案慣例(kebab-case、命名匯出、匯入順序、import type、命名常數)

(您必須根據使用案例選擇正確的模型——追求準確度選擇 gpt-4o-transcribe,需要時間戳記/SRT/VTT 輸出選擇 whisper-1,需要說話者標籤選擇 gpt-4o-transcribe-diarize)

(您必須在將音訊檔案傳送到 API 之前,將大於 25 MB 的檔案進行分段處理——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

範例索引


理念

OpenAI Audio API 透過多種針對不同需求最佳化的模型,提供語音轉文字轉錄與翻譯。此 API 很簡單——您發送一個音訊檔案,然後獲得文字回來——但選擇正確的模型、回應格式和參數對於獲得高品質結果至關重要。

核心原則:

  1. 模型選擇至關重要 —— gpt-4o-transcribe 能產生最高的準確度和較低的幻覺率。whisper-1 是唯一支援帶時間戳記的 SRT/VTT/verbose_json 格式的模型。gpt-4o-transcribe-diarize 新增了說話者識別功能。
  2. 檔案大小是主要限制 —— 25 MB 限制意味著您必須對較長音訊進行分段。應在句子邊界處分割以保留語境。
  3. 提示能提高準確度 —— prompt 參數引導詞彙、縮寫和格式風格。它並非提供指令——而是提供模型比對的語境。
  4. 回應格式決定可用功能 —— 時間戳記需要在 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-1gpt-4o-transcribegpt-4o-mini-transcribegpt-4o-transcribe-diarize
回應格式json, text, srt, vtt, verbose_jsonjson, textjson, textjson, text, diarized_json
時間戳記詞級 + 段級無無無
串流無有有無
提示支援有(224 tokens)有有無
對數機率無有有無
說話者標籤無無無有
語言參數有有有有

模式 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 事件以獲得完成狀態。請勿將 stream: true 與 whisper-1 一起使用——它不受支援。

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);
}

請參閱 core.md 以取得完整的串流和對數機率範例。


模式 6:翻譯為英語

將非英語音訊翻譯為英語文字。僅 whisper-1 透過 audio.translations.create() 支援此功能。對於同語言轉錄,請改用 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 秒的音訊剪輯作為 data 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>

紅旗標誌

高優先級問題:

  • 在 whisper-1 上使用 timestamp_granularities 但未搭配 response_format: "verbose_json"(會被靜默忽略)
  • 發送大於 25 MB 的檔案(API 會回傳錯誤)
  • 對超過 30 秒的音訊使用 gpt-4o-transcribe-diarize 但未設定 chunking_strategy(API 會回傳錯誤)
  • 將 stream: true 與 whisper-1 一起使用(不受支援)

中優先級問題:

  • 在 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 個 tokens。較長的提示會被截斷。
  • 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 翻譯成其他語言。
  • 串流轉錄會發射出帶有 delta 字串屬性的 transcript.text.delta 事件,以及最終的 transcript.text.done 事件。

</red_flags>


<critical_reminders>

關鍵提醒

**

…

[truncated for translation]

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

相關技能