음성 합성
BizRouter는 텍스트를 자연스러운 음성으로 변환하는 TTS(Text-to-Speech) 기능을 지원합니다. 다양한 음성으로 오디오를 생성할 수 있습니다. 실시간 대화, 음성 대화, 음성 인식과의 차이는 오디오 API 에서 비교할 수 있습니다. 음성 합성 모델 선택 GET /v1/models 에서 api_type 이 audio_speech 인 모델을 선택해야 합니다. output_modalities 에 audio가 있더라도 gpt-realtime과 gpt-audio 계열은 이 엔드포인트에서 호출할 수 없습니다. 현재 Gemini TTS 모델과 OpenAI gpt-4o-mini-tts 를 호출할 수 있습니다. 모델에 따라 사용할 수 있는 파라미터와 출력 형식이 다르므로 아래 표를 확인해야 합니다.
모델별 지원 범위
같은 endpoint지만 받는 파라미터가 다릅니다 파라미터 Gemini TTS gpt-4o-mini-tts voice Kore 등 30종 alloy, ash, ballad, coral, echo, sage, shimmer, verse 등 speakers 최대 2명 (2.5 모델만 지원, 3.8 모델은 400 거절) 미지원 instructions 미지원 (input 텍스트에 직접 지시) 지원 response_format 미지원 (2.5: raw PCM, 3.8: WAV — 응답 Content-Type으로 구분) mp3, opus, aac, flac, wav, pcm speed 미지원 0.25 ~ 4.0 지원하지 않는 파라미터를 보내면 무시하지 않고 400으로 거절합니다. 조용히 무시하면 요청한 것과 다른 오디오가 200으로 돌아오기 때문입니다.
OpenAI TTS 사용하기
gpt-4o-mini-tts는 말투를 문장으로 지시할 수 있습니다
OpenAI TTS 사용하기 · cURL 예시
응답은 바로 재생 가능한 파일입니다 Gemini 3.8 TTS( gemini-3.8-flash-tts , gemini-3.8-flash-lite-tts )는 RIFF 헤더가 포함된 WAV 파일을 그대로 돌려주고, Gemini 2.5 TTS는 raw PCM을 돌려줍니다. gpt-4o-mini-tts는 response_format 에 지정한 컨테이너 그대로 돌려주므로, 처리 방식은 응답의 Content-Type 으로 결정합니다. 요금은 음성 토큰으로 계산됩니다 gpt-4o-mini-tts는 텍스트 출력이 없고 말한 오디오가 곧 출력입니다. X-Output-Tokens 헤더와 청구 내역의 출력량은 이 음성 토큰 수이며, 텍스트 출력 단가가 아니라 음성 출력 단가로 계산됩니다.
API 엔드포인트
Text-to-Speech API
API 엔드포인트 · 요청 파라미터
model TTS 모델 ID (필수) input 음성으로 변환할 텍스트 (필수, 길이 제한은 Provider 정책에 따름) voice 음성 이름 (필수, 아래 음성 목록 참조)
지원 음성
30개의 사전 정의된 음성 사용 가능
스타일 프롬프트
음성의 톤과 감정을 input 텍스트에 직접 지시 Gemini 2.5 TTS는 자연어로 음성 스타일을 지시할 수 있습니다. 스타일 프롬프트를 input 텍스트 앞에 포함시키면 됩니다. 3.8 모델은 input을 그대로 읽습니다 Gemini 3.8 TTS는 input 텍스트를 화면에 표시된 대본 그대로 취급합니다. 아래 같은 스타일 프롬프트를 넣으면 지시문이 음성으로 그대로 읽히므로, 3.8 모델에서는 읽을 문장만 input에 넣고 감정 표현은 <laugh> , <sigh> , <short pause> 같은 인라인 태그로 표현합니다.
스타일 프롬프트 · 스타일 프롬프트 예시
다큐멘터리 내레이션 친근한 AI 어시스턴트 무서운 분위기
마크업 태그
비언어적 표현과 발화 스타일 제어 텍스트 내에 마크업 태그를 사용하여 비언어적 소리나 특정 발화 스타일을 지정할 수 있습니다. 비언어 소리 스타일 일시정지 [sigh] 한숨 소리 [laughing] 웃음 소리 [clears throat] 헛기침 [gasp] 헐떡임/놀람 [uhm] 머뭇거림 [whispering] 속삭이는 목소리 [shouting] 외치는 목소리 [extremely fast] 매우 빠른 말하기 [sarcasm] 비꼬는 톤 [excited] 신난 목소리 [short pause] 짧은 일시정지 [medium pause] 중간 일시정지 [long pause] 긴 일시정지
멀티 스피커
최대 2명의 화자가 대화하는 오디오 생성 멀티 스피커 지원 Gemini 2.5 TTS 모델은 최대 2명의 화자가 대화하는 오디오를 생성할 수 있습니다. 각 화자에게 다른 음성을 지정하여 자연스러운 대화 오디오를 만들 수 있습니다. 3.8 모델은 화자 라벨을 대화 지시가 아니라 읽을 대본으로 취급하므로 speakers 요청을 400으로 거절합니다. 멀티 스피커가 필요하면 2.5 모델을 사용합니다.
멀티 스피커 · 대화형 텍스트 형식
input 텍스트에 화자 이름과 콜론(:)으로 대화를 구분합니다. speakers 파라미터에서 지정한 화자 이름과 정확히 일치해야 합니다.
응답 형식
오디오 바이너리 데이터 직접 반환 출력 형식은 모델 세대에 따라 다릅니다 응답은 JSON이 아닌 오디오 바이너리입니다. Gemini 2.5 TTS는 헤더 없는 raw PCM (24kHz, 16-bit, 모노)이고, Gemini 3.8 TTS는 RIFF 헤더가 포함된 WAV 파일 그대로입니다. 어떤 바이트가 왔는지는 Content-Type 으로 구분합니다.
응답 형식 · 응답 헤더
Content-Type audio/pcm (2.5) · audio/wav (3.8) · 요청한 response_format (OpenAI) X-Request-ID 요청 추적 ID X-Input-Tokens 입력 토큰 수 X-Output-Tokens 출력 토큰 수
응답 형식 · 오디오 사양
샘플 레이트 24,000 Hz 비트 깊이 16-bit 채널 Mono 인코딩 PCM (Linear16)
클라이언트 구현 예제
TTS API 호출 및 오디오 재생 코드 cURL Node.js Python
에러 처리
TTS 요청 실패 시 응답
에러 처리 · 일반적인 에러 코드
400 잘못된 요청 (음성 이름 오류, 모델 오류 등) 401 인증 실패 (API 키 오류) 429 요청 한도 초과 500 서버 내부 오류
제한사항
입력 길이 제한 Provider별 상이 Speaker 수 최대 2명 출력 형식 Gemini: PCM / OpenAI: 6종 오디오 형식 변환 Gemini TTS는 PCM 형식만 출력하므로, MP3나 WAV가 필요하면 클라이언트에서 ffmpeg 등으로 변환해야 합니다. gpt-4o-mini-tts는 response_format 으로 바로 지정할 수 있습니다. 스트리밍 미지원 현재 TTS API는 스트리밍을 지원하지 않습니다. 전체 오디오가 생성된 후 한 번에 반환됩니다. TTS는 대화를 이어 가지 않습니다 입력 문장을 그대로 읽는 음성 파일이 필요할 때 사용해야 합니다. 음성을 이해하고 답변까지 생성하려면 gpt-audio , 사용자가 말하는 동안 응답해야 하면 Realtime API 가 적합합니다.