API

텍스트 음성 변환

요약

Gateway TTS API는 Google Gemini TTS 모델을 사용하여 텍스트를 자연스러운 음성 오디오로 변환합니다. 30가지 음성, 감정 표현을 위한 오디오 태그, 다화자 대화를 지원합니다. 응답은 직접 재생하거나 WAV 등 표준 오디오 포맷으로 변환할 수 있는 원시 PCM 오디오 데이터로 반환됩니다.

공식 문서: Google 음성 생성 가이드

API	지원 모델
gateway/audio/speech	`gemini-3.1-flash-tts-preview` (권장) `gemini-2.5-flash-preview-tts`

텍스트 음성 변환

POST

/v1/api/gateway/audio/speech

지정한 model과 voice를 사용하여 input 텍스트에서 음성 오디오를 생성합니다. 응답은 원시 PCM 오디오 바이트(24kHz, 16-bit, 모노)로 반환됩니다.

보다 자세한 사용법은 Google 음성 생성 가이드를 참고하세요.

요청 헤더


json
Authorization: Bearer {api-key}

파라미터

model

string

required

음성 생성에 사용할 TTS 모델의 이름입니다.

모델	설명
`gemini-3.1-flash-tts-preview`	오디오 태그를 지원하는 최신 모델. 권장.
`gemini-2.5-flash-preview-tts`	이전 세대 TTS 모델.

input

string

required

음성으로 변환할 텍스트입니다. 최대 4,000자까지 지원합니다.

감정 표현을 위한 200개 이상의 오디오 태그를 지원합니다 (Gemini 3.1 전용). 예: [whispers], [shouting], [excited], [sighs], [laughs], [singing], [cheerful], [sad], [angry].

오디오 태그 사용 예시:

[cheerful] FactChat에 오신 것을 환영합니다! [excited] 오늘 보여드릴 놀라운 기능들이 있습니다.

voice

string

사용할 음성의 이름입니다. 기본값: "Aoede".

30가지 옵션은 아래 사용 가능한 음성 표를 참고하세요.

speakers

object

다화자 구성 객체로, 화자 이름을 음성 이름에 매핑합니다. 이 파라미터를 사용할 때는 input 텍스트를 각 줄에 화자이름: 대사 형식으로 작성합니다.

예시:


json
{
  "speakers": {
    "Joe": "Puck",
    "Jane": "Kore"
  },
  "input": "Joe: 안녕하세요! 오늘 어떠세요?\nJane: 좋아요, 물어봐 주셔서 감사합니다!"
}

사용 가능한 음성

음성	성별	톤
Zephyr	여성	밝은
Puck	남성	경쾌한
Charon	남성	정보 전달형
Kore	여성	단호한
Fenrir	남성	흥분된
Leda	여성	젊은
Orus	남성	단호한
Aoede	여성	산뜻한
Callirrhoe	여성	편안한
Autonoe	여성	밝은
Enceladus	남성	나직한
Iapetus	남성	맑은
Umbriel	남성	편안한
Algieba	남성	부드러운
Despina	여성	부드러운
Erinome	여성	맑은
Algenib	남성	거친
Rasalgethi	남성	정보 전달형
Laomedeia	여성	경쾌한
Achernar	여성	부드러운
Alnilam	남성	단호한
Schedar	남성	차분한
Gacrux	여성	성숙한
Pulcherrima	여성	적극적인
Achird	남성	친근한
Zubenelgenubi	남성	캐주얼한
Vindemiatrix	여성	온화한
Sadachbia	남성	활기찬
Sadaltager	남성	박식한
Sulafat	여성	따뜻한

오디오 태그 (Gemini 3.1 전용)

Gemini 3.1 Flash TTS는 생성된 음성의 표현력과 감정을 제어하는 200개 이상의 오디오 태그를 지원합니다. 입력 텍스트에 태그를 직접 삽입하여 모델의 발화 방식을 조절할 수 있습니다.

감정 태그: [cheerful], [sad], [angry], [excited], [surprised], [calm]

동작 태그: [whispers], [shouting], [sighs], [laughs], [singing], [gasps]

스타일 태그: [slowly], [quickly], [softly], [loudly]

오디오 태그는 gemini-3.1-flash-tts-preview 모델에서만 지원됩니다. gemini-2.5-flash-preview-tts 모델에서는 태그가 적용되지 않습니다.

다화자 (Multi-Speaker)

여러 화자의 음성을 생성하려면 speakers 파라미터를 사용하여 화자 이름을 음성에 매핑하고, input 텍스트를 각 줄에 화자이름: 대사 형식으로 작성합니다.


json
{
  "model": "gemini-3.1-flash-tts-preview",
  "speakers": {
    "면접관": "Charon",
    "게스트": "Leda"
  },
  "input": "면접관: 쇼에 오신 것을 환영합니다! 자기소개 부탁드립니다.\n게스트: 초대해 주셔서 감사합니다! 이 자리에 올 수 있어 기쁩니다."
}

응답

API는 다음 특성을 가진 원시 PCM 오디오 바이트를 반환합니다:

속성	값
Content-Type	`audio/pcm`
샘플 레이트	24,000 Hz
채널	1 (모노)
비트 깊이	16-bit

응답 헤더:

헤더	설명
`X-Input-Tokens`	소비된 입력 토큰 수
`X-Output-Tokens`	소비된 출력 토큰 수

원시 PCM 데이터를 재생 가능한 WAV 파일로 변환하려면 위 파라미터로 표준 WAV 헤더를 추가하세요.

크레딧 비용

모델	입력 비용	출력 비용
`gemini-3.1-flash-tts-preview`	10 크레딧 / 1만 토큰	200 크레딧 / 1만 토큰
`gemini-2.5-flash-preview-tts`	5 크레딧 / 1만 토큰	100 크레딧 / 1만 토큰

마지막 수정 날짜: Apr 16, 2026

/images/edit