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 사용
예제 인덱스
- 핵심: 전사, 번역, 타임스탬프, 청크 분할, 스트리밍, 화자 분리 – 모든 오디오 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 토큰) | 예 | 예 | 없음 |
| 로그프로브 | 없음 | 예 | 예 | 없음 |
| 화자 레이블 | 없음 | 없음 | 없음 | 예 |
| 언어 매개변수 | 예 | 예 | 예 | 예 |
패턴 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>
중요 알림
**