Communitygithub.com

majiayu000/claude-skill-registry

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

claude-skill-registry 是什么?

该技能提供了OpenAI音频API的全面模式,专注于语音转文字转录和翻译。它支持多种模型,包括用于高精度的`gpt-4o-transcribe`、用于成本效益的`gpt-4o-mini-transcribe`、用于时间戳和字幕的`whisper-1`以及用于说话人识别的`gpt-4o-transcribe-diarize`。AI代理可使用此技能处理音频文件转录(如会议、采访),生成SRT/VTT字幕,识别多说话人对话中的说话人。该技能详细介绍了关键模式:模型选择、提示以提高特定词汇的准确性、处理大于25 MB的文件分块、流式转录输出以及翻译到英语。它包含红牌警告以应对常见错误,例如在`whisper-1`上使用`timestamp_granularities`而不配合`verbose_json`格式,或发送超过限制的文件。此技能适用于Claude Code、Cursor、Codex等平台,提供示例和代码片段以便于集成。

兼容平台✓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用于精度,whisper-1用于时间戳/SRT/VTT输出,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音频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秒音频片段,格式为数据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)

转录与翻译

音频是否是英语?
+-- 是 -> 使用 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(不被支持)

中优先级问题:

  • 使用whisper-1而gpt-4o-transcribe可以产生更高精度时(whisper-1具有更高的幻觉率)
  • 在知道语言的情况下未传递language参数(对于短音频或嘈杂音频,自动检测可能错误)
  • 当您想要同语言转录时却使用了audio.translations.create()(翻译总是输出英语)
  • 分块时在句子中间拆分音频(在边界处丢失上下文)

常见错误:

  • 将prompt参数视为指令(“请仔细转录”)——它是用于词汇和风格匹配的上下文
  • 当您需要SRT/VTT输出时使用gpt-4o-transcribe——只有whisper-1支持这些格式
  • 期望gpt-4o-transcribe-diarize支持提示或对数概率(它不支持)
  • 对英语音频使用翻译端点(它只将非英语翻译为英语)
  • 转录拆分文件时未提供前一个分块上下文(降低边界处的准确性)

陷阱与边界情况:

  • whisper-1上的prompt参数限制约为224个token。更长的提示会被截断。
  • 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>

关键提示

**

…[为翻译而截断]

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.

相关技能