Communitygithub.com

majiayu000/claude-skill-registry-data

通过 OpenAI 音频 API 进行语音转文字转录和翻译——涵盖模型、响应格式、时间戳、提示词、流式传输、音频分块和说话人识别。

claude-skill-registry-data 是什么?

这是一个针对 OpenAI Audio API 的 Claude Code 技能,专注于语音转文字 (STT) 和翻译任务。它提供了从基本转录到高级模式(如说话人识别(diarization)、流式输出和时间戳生成)的全面策略。该技能的核心在于帮助开发者在不同模型(`whisper-1`、`gpt-4o-transcribe`、`gpt-4o-mini-transcribe` 和 `gpt-4o-transcribe-diarize`)之间做出正确选择,每个模型在准确率、成本、输出格式(JSON、SRT、VTT、verbose_json)和功能上各有千秋。通过清晰地做出决策框架和列出常见陷阱,它避免了因文件超过 25MB、错误使用模型或参数不匹配而导致的常见错误。该技能适用于所有主要的 AI 助手平台(如 Claude Code、Cursor、Codex),其文档(SKILL.md)包含详细的 TypeScript 代码示例和参数指南,指导用户通过流式传输处理大型音频、通过提示词提高术语准确性,以及利用 `verbose_json` 和 `diarized_json` 等响应格式实现视频编辑和会议记录等专业用例。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/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;对于时间戳/SRT/VTT,选择 whisper-1;对于说话人识别,选择 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() 翻译为英语
  • 使用说话人参考进行说话人识别(diarization)

何时不使用:

  • 文本转语音 (TTS) —— 使用 OpenAI TTS API (client.audio.speech.create())
  • 实时双向语音对话 —— 使用 OpenAI Realtime API
  • 使用非 OpenAI 提供商进行转录 —— 使用提供商无关的语音 SDK

示例索引


哲学

OpenAI 音频 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 上可用。

何时使用音频 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 事件以完成。不要在 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);
}

有关完整的流式传输和对数概率示例,请参见 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:说话人识别 (Diarization)

识别多说话人音频中的说话人。使用 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"
+-- 带文本字段的 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 返回错误)
  • 在 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 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。其他格式必须首先转换。
  • 除非你提供包含短音频片段的 known_speaker_names 和 known_speaker_references,否则 gpt-4o-transcribe-diarize 将说话人标记为“A”、“B”、“C”。
  • 翻译端点仅支持 whisper-1,并且仅输出英语 —— 无法通过此 API 翻译成其他语言。
  • 流式转录会发出带有 delta 字符串属性的 transcript.text.delta 事件,以及最终的 transcript.text.done 事件。

</red_flags>


<critical_reminders>

关键提醒

**…

[已截断以进行翻译]

Individual skills in this repo

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

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

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-data

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-data

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-data

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-data

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-data

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-data

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

majiayu000/claude-skill-registry-data

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-data

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-data

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-data

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

majiayu000/claude-skill-registry-data

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

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Understand an existing codebase through systematic exploration

majiayu000/claude-skill-registry-data

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".

相关技能