Communitygithub.com

majiayu000/claude-skill-registry-data

OpenAI Audio API를 통한 음성-텍스트 변환 및 번역 — 모델, 응답 형식, 타임스탬프, 프롬프팅, 스트리밍, 청킹, 화자 분리

claude-skill-registry-data란 무엇인가요?

이 스킬은 OpenAI Audio API를 활용하여 음성을 텍스트로 변환하고 번역하는 기능을 제공합니다. 개발자는 `gpt-4o-transcribe`를 통해 높은 정확도의 전사를 얻거나, `whisper-1`로 타임스탬프와 자막(SRT/VTT)을 생성할 수 있습니다. 또한 `gpt-4o-transcribe-diarize` 모델을 사용하면 여러 화자가 있는 오디오에서 화자 식별(화자 분리)이 가능합니다. 파일 크기가 25MB를 초과하는 경우 반드시 청킹해야 하며, `prompt` 매개변수로 어휘와 스타일을 가이드할 수 있습니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트 기반 개발 환경에서 사용되며, SKILL.md 문서에 모델 선택, 응답 형식, 타임스탬프 생성, 청킹, 스트리밍, 화자 분리 등 모든 핵심 패턴이 상세히 설명되어 있습니다.

지원 대상✓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에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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 순서, 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 사용

예제 인덱스


철학

OpenAI Audio API는 다양한 요구에 최적화된 여러 모델을 통해 음성-텍스트 전사 및 번역을 제공합니다. API는 간단합니다. 오디오 파일을 보내고 텍스트를 받습니다. 하지만 올바른 모델, 응답 형식, 매개변수를 선택하는 것이 결과 품질에 매우 중요합니다.

핵심 원칙:

  1. 모델 선택이 중요합니다. gpt-4o-transcribe는 가장 높은 정확도와 낮은 환각률을 제공합니다. whisper-1은 타임스탬프가 있는 SRT/VTT/verbose_json을 지원하는 유일한 모델입니다. gpt-4o-transcribe-diarize는 화자 식별 기능을 추가합니다.
  2. 파일 크기가 주요 제약입니다. 25MB 제한으로 인해 긴 오디오는 청킹해야 합니다. 컨텍스트를 유지하려면 문장 경계에서 분할하세요.
  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 토큰)예예아니요
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: 스트리밍 전사

모델이 오디오를 처리하는 동안 부분 전사 결과를 스트리밍합니다. 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초 오디오 클립, 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에서 response_format: "verbose_json" 없이 timestamp_granularities 사용 (무시됨)
  • 25MB보다 큰 파일 전송 (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는 known_speaker_names와 known_speaker_references(짧은 오디오 클립 포함)를 제공하지 않으면 화자에게 "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".

관련 스킬