Communitygithub.com

majiayu000/claude-skill-registry

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

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

이 스킬은 OpenAI Audio API를 사용하여 음성 파일을 텍스트로 변환(음성-텍스트)하고 비영어권 오디오를 영어로 번역하는 방법을 포괄적으로 설명합니다. 개발자는 `gpt-4o-transcribe`(최고 정확도), `gpt-4o-mini-transcribe`(비용 효율), `whisper-1`(타임스탬프/SRT/VTT 자막), `gpt-4o-transcribe-diarize`(화자 분리) 중에서 작업에 맞는 모델을 선택해야 합니다. API는 25MB 파일 크기 제한이 있으므로 긴 오디오는 반드시 문장 경계를 기준으로 청크로 분할해야 합니다. `prompt` 파라미터를 통해 어휘, 약어, 스타일을 안내하여 인식 정확도를 높일 수 있으며, `stream: true` 옵션으로 실시간 스트리밍 전사가 가능합니다. 이 스킬은 Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있도록 설계되었으며, SKILL.md 파일에 상세한 패턴, 결정 프레임워크, 주의 사항이 포함되어 있습니다.

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

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

문서

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의 프로젝트 규칙(kebab-case, 명명된 내보내기, import 순서, import type, 명명된 상수)을 따라야 합니다.

(사용 사례에 맞는 모델을 반드시 선택해야 합니다 – gpt-4o-transcribe는 정확도, whisper-1은 타임스탬프/SRT/VTT 출력, 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)
  • 타임스탬프 (단어 수준, 구간 수준) 및 자막 생성
  • 어휘, 약어 및 스타일을 위한 프롬프팅
  • 컨텍스트를 유지하며 대용량 파일(> 25MB) 청크로 분할
  • 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 토큰)예예없음
로그프로브없음예예없음
화자 레이블없음없음없음예
언어 매개변수예예예예

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

전체 스트리밍 및 로그프로브 예제는 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(데이터 URL 형식의 2-10초 오디오 클립)를 제공하여 세그먼트를 알려진 화자(최대 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가 프롬프트 또는 로그프로브를 지원할 것이라고 기대 (지원하지 않음)
  • 영어 오디오에 번역 엔드포인트 사용 (비영어를 영어로만 번역함)
  • 분할된 파일을 전사할 때 이전 청크 컨텍스트를 제공하지 않음 (경계에서 정확도 감소)

주의사항 및 예외 사항:

  • whisper-1에서 prompt 매개변수는 약 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

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.

관련 스킬