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 사용
예제 인덱스
- 핵심: 전사, 번역, 타임스탬프, 청킹, 스트리밍, 화자 분리 -- 모든 오디오 API 패턴
철학
OpenAI Audio API는 다양한 요구에 최적화된 여러 모델을 통해 음성-텍스트 전사 및 번역을 제공합니다. API는 간단합니다. 오디오 파일을 보내고 텍스트를 받습니다. 하지만 올바른 모델, 응답 형식, 매개변수를 선택하는 것이 결과 품질에 매우 중요합니다.
핵심 원칙:
- 모델 선택이 중요합니다.
gpt-4o-transcribe는 가장 높은 정확도와 낮은 환각률을 제공합니다.whisper-1은 타임스탬프가 있는 SRT/VTT/verbose_json을 지원하는 유일한 모델입니다.gpt-4o-transcribe-diarize는 화자 식별 기능을 추가합니다. - 파일 크기가 주요 제약입니다. 25MB 제한으로 인해 긴 오디오는 청킹해야 합니다. 컨텍스트를 유지하려면 문장 경계에서 분할하세요.
- 프롬프팅은 정확도를 향상시킵니다.
prompt매개변수는 어휘, 약어, 형식 스타일을 안내합니다. 명령을 내리는 것이 아니라 모델이 매칭할 컨텍스트를 제공합니다. - 응답 형식에 따라 사용 가능한 기능이 결정됩니다. 타임스탬프는
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-1 | gpt-4o-transcribe | gpt-4o-mini-transcribe | gpt-4o-transcribe-diarize |
|---|---|---|---|---|
| 응답 형식 | json, text, srt, vtt, verbose_json | json, text | json, text | json, 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>
중요 알림
**
…
[번역을 위해 잘림]