OpenAI 오디오 형식¶
공식 문서
📝 소개¶
OpenAI Audio API는 세 가지 주요 기능을 제공합니다:
- Text-to-Speech (TTS) - 텍스트를 자연스러운 음성으로 변환
- Speech-to-Text (STT) - 오디오를 텍스트로 전사
- Audio Translation - 비영어 오디오를 영어 텍스트로 번역
💡 요청 예시¶
텍스트-음성 변환 ✅¶
curl https://ssanai-workspace.atto-lab.cc/v1/audio/speech \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "tts-1",
"input": "Hello, world!",
"voice": "alloy"
}' \
--output speech.mp3
지원 모델¶
tts-1: 빠른 응답 속도의 표준 모델tts-1-hd: 더 높은 오디오 품질의 고품질 모델
지원 음성¶
voice 파라미터는 다양한 음성 옵션을 지원합니다:
- alloy: 균형 잡히고 자연스러운 음성
- coral: 따뜻하고 부드러운 여성형 음성, 라이프스타일/고객 응대에 적합
- echo: 깊고 안정적인 남성형 음성, 시스템 안내/설명 텍스트에 적합
- fable: 가볍고 이야기체 느낌의 음성, 오디오북/스토리텔링에 적합
- onyx: 깊고 묵직한 남성형 음성, 공식/전문 상황에 적합
- nova: 밝고 젊은 여성형 음성, 활기/창의 콘텐츠에 적합
- shimmer: 맑고 가벼운 여성형 음성, 짧은 안내/교육 콘텐츠에 적합
- sage: 차분하고 자연스러운 중립 음성, 설명/중립 내레이션에 적합
음성-텍스트 변환 ✅¶
curl https://ssanai-workspace.atto-lab.cc/v1/audio/transcriptions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: multipart/form-data" \
-F file="@/path/to/file/audio.mp3" \
-F model="whisper-1"
응답 예시:
오디오 번역 ✅¶
curl https://ssanai-workspace.atto-lab.cc/v1/audio/translations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: multipart/form-data" \
-F file="@/path/to/file/chinese.mp3" \
-F model="whisper-1"
응답 예시:
📮 요청¶
엔드포인트¶
텍스트-음성 변환¶
텍스트를 음성으로 변환합니다.
음성-텍스트 변환¶
입력 언어의 오디오를 텍스트로 전사합니다.
오디오 번역¶
오디오를 영어 텍스트로 번역합니다.
인증 방법¶
요청 헤더에 다음 값을 포함하여 API 키 인증을 수행하세요:
$API_KEY는 발급받은 API 키입니다.
요청 본문 파라미터¶
텍스트-음성 변환¶
model¶
- 유형: String
- 필수: Yes
- 선택 값: tts-1, tts-1-hd
- 설명: TTS model to use
input¶
- 유형: String
- 필수: Yes
- 최대 길이: 4096자
- 설명: 음성으로 변환할 텍스트
voice¶
- 유형: String
- 필수: Yes
- 선택 값: alloy, echo, fable, onyx, nova, shimmer
- 설명: 음성 생성에 사용할 보이스
response_format¶
- 유형: String
- 필수: No
- 기본값: mp3
- 선택 값: mp3, opus, aac, flac, wav, pcm
- 설명: 오디오 출력 형식
speed¶
- 유형: Number
- 필수: No
- 기본값: 1.0
- Range: 0.25 - 4.0
- 설명: 생성 음성 속도
음성-텍스트 변환¶
file¶
- 유형: File
- 필수: Yes
- 지원 형식: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm
- 설명: 전사할 오디오 파일
model¶
- 유형: String
- 필수: Yes
- 현재는 whisper-1만 지원합니다.
- 설명: Model ID to use
language¶
- 유형: String
- 필수: No
- Format: ISO-639-1 (e.g., "en")
- 설명: 오디오 언어(지정 시 정확도 향상 가능)
prompt¶
- 유형: String
- 필수: No
- 설명: 모델 스타일 유도 또는 이전 오디오 세그먼트에서 이어가기 위한 텍스트
response_format¶
- 유형: String
- 필수: No
- 기본값: json
- 선택 값: json, text, srt, verbose_json, vtt
- 설명: Output format
temperature¶
- 유형: Number
- 필수: No
- 기본값: 0
- Range: 0 - 1
- 설명: 샘플링 온도입니다. 값이 높을수록 출력이 더 무작위해집니다.
timestamp_granularities¶
- 유형: Array
- 필수: No
- 기본값: segment
- 선택 값: word, segment
- 설명: 전사 타임스탬프 세분화 수준
오디오 번역¶
file¶
- 유형: File
- 필수: Yes
- 지원 형식: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm
- 설명: 번역할 오디오 파일
model¶
- 유형: String
- 필수: Yes
- 현재는 whisper-1만 지원합니다.
- 설명: Model ID to use
prompt¶
- 유형: String
- 필수: No
- 설명: 모델 스타일을 유도하기 위한 영어 텍스트
response_format¶
- 유형: String
- 필수: No
- 기본값: json
- 선택 값: json, text, srt, verbose_json, vtt
- 설명: Output format
temperature¶
- 유형: Number
- 필수: No
- 기본값: 0
- Range: 0 - 1
- 설명: 샘플링 온도입니다. 값이 높을수록 출력이 더 무작위해집니다.
📥 응답¶
성공 응답¶
텍스트-음성 변환¶
바이너리 오디오 파일 콘텐츠를 반환합니다.
음성-텍스트 변환¶
기본 JSON 형식¶
상세 JSON 형식¶
{
"task": "transcribe",
"language": "english",
"duration": 8.47,
"text": "Complete transcribed text",
"segments": [
{
"id": 0,
"seek": 0,
"start": 0.0,
"end": 3.32,
"text": "Segmented transcribed text",
"tokens": [50364, 440, 7534],
"temperature": 0.0,
"avg_logprob": -0.286,
"compression_ratio": 1.236,
"no_speech_prob": 0.009
}
]
}
오디오 번역¶
오류 응답¶
요청 처리 중 문제가 발생하면 API는 4XX-5XX 범위의 HTTP 상태 코드와 함께 오류 응답 객체를 반환합니다.
주요 오류 상태 코드¶
400 Bad Request: 잘못된 요청 파라미터401 Unauthorized: API 키가 유효하지 않거나 누락됨429 Too Many Requests: API 호출 한도 초과500 Internal Server Error: 서버 내부 오류
오류 응답 예시: