Gemini TTS

이 페이지는 오디오 (Audio) 페이지의 Gemini 네이티브 형식을 확장하며, 차세대 TTS 모델을 다룹니다.

인증

Authorization: Bearer sk-xxxxxxxxxx

Gemini 네이티브 형식 (TTS)

POST https://api.gravitex.ai/v1beta/models/{model}:generateContent

{model}은 gemini-3.8-flash-tts 또는 gemini-3.1-flash-tts-preview입니다.

gemini-3.8-flash-tts

curl "https://api.gravitex.ai/v1beta/models/gemini-3.8-flash-tts:generateContent" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "오늘의 기술 아침 뉴스를 시작합니다.<short pause>첫 번째 소식입니다. 연구진이 상온 초전도 소재에서 획기적인 성과를 발표했습니다.",
            "speech_metadata": { "speaker": "Host", "style": "뉴스 방송, 또렷하고 열정적으로" }
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": {
          "prebuiltVoiceConfig": { "voiceName": "Kore" }
        }
      }
    }
  }'

gemini-3.1-flash-tts-preview

curl "https://api.gravitex.ai/v1beta/models/gemini-3.1-flash-tts-preview:generateContent" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "밝은 어조로 말해 주세요: 오늘도 좋은 하루 보내세요!" }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": {
          "prebuiltVoiceConfig": { "voiceName": "Kore" }
        }
      }
    }
  }'

응답

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "inlineData": { "mimeType": "audio/wav", "data": "UklGRi4..." } }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 1680,
    "totalTokenCount": 1685,
    "candidatesTokensDetails": [ { "modality": "AUDIO", "tokenCount": 1680 } ]
  },
  "modelVersion": "gemini-3.8-flash-tts",
  "responseId": "xxxx",
  "createTime": "2026-10-10T10:00:00Z"
}

필드	설명
`candidates[].content.parts[].inlineData.mimeType`	오디오 형식, 아래 처리 표 참조
`candidates[].content.parts[].inlineData.data`	base64 오디오
`candidates[].finishReason`	`STOP`(정상 종료) 또는 기타 중단 사유
`usageMetadata.promptTokenCount`	텍스트 입력 토큰(과금 기준)
`usageMetadata.candidatesTokenCount`	오디오 출력 토큰(과금 기준)
`usageMetadata.totalTokenCount`	합계
`usageMetadata.candidatesTokensDetails[].modality`	모달리티별 내역, 오디오 출력은 `AUDIO`
`modelVersion` / `responseId` / `createTime`	실제 모델 버전 / 요청 ID / 시간

응답 처리

오디오는 candidates[0].content.parts[0].inlineData로 반환됩니다:

echo "<base64_data>" | base64 --decode > out.wav

모델	mimeType	처리 방법
gemini-3.8-flash-tts	`audio/wav`	디코딩하면 바로 재생 가능한 완전한 WAV
gemini-3.1-flash-tts-preview	`audio/l16;codec=pcm;rate=24000`	순수 PCM이므로 WAV 헤더를 추가해야 함. 실제 파라미터는 응답의 `mimeType`을 따름

3.1용 WAV 헤더 추가(Python, 샘플링 레이트는 응답의 mimeType에서 파싱하고 하드코딩하지 마세요):

import base64, json, struct

resp = json.load(open("response.json"))
inline = resp["candidates"][0]["content"]["parts"][0]["inlineData"]
pcm = base64.b64decode(inline["data"])

# mimeType 예: audio/l16;codec=pcm;rate=24000, rate=에서 파싱
rate = 24000
for part in inline["mimeType"].split(";"):
    if part.strip().startswith("rate="):
        rate = int(part.strip()[5:])

header = (b"RIFF" + struct.pack("<I", 36 + len(pcm)) + b"WAVE"
          + b"fmt " + struct.pack("<IHHIIHH", 16, 1, 1, rate, rate * 2, 2, 16)
          + b"data" + struct.pack("<I", len(pcm)))
open("speech.wav", "wb").write(header + pcm)

파라미터 설명

파라미터	설명
`contents[].parts[].text`	읽을 텍스트. 3.1은 스타일 지시를 여기에 작성(예: “밝은 어조로 말해 주세요:“)
`contents[].parts[].speech_metadata.speaker`	화자 라벨(3.8 전용, 다중 화자는 매 턴 필수)
`contents[].parts[].speech_metadata.style`	지속되는 낭독 스타일(3.8 전용, 속삭임·속도 등)
`generationConfig.responseModalities`	`["AUDIO"]`로 고정
`generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName`	음성 ID, 음성 라이브러리에서 조회
`generationConfig.speechConfig.multiSpeakerVoiceConfig`	다중 화자 설정

인라인 태그(두 세대 공통, 본문에 작성하여 순간적인 이벤트 제어): <laugh>, <sigh>, <cough>, <breath>, <short pause>. 멀티턴: 3.8은 긴 멀티턴 대화를 안정적으로 지원하며, 3.1은 단일 턴만 지원합니다. contents에는 user 턴이 하나만 있어야 하며 여러 턴이면 Multiturn chat is not enabled for this model이 반환됩니다. 멀티턴이 필요하면 gemini-3.8-flash-tts를 사용하세요. 다중 화자(3.8): 각 part에 speech_metadata.speaker를 지정하며, 화자는 speechConfig에 설정된 화자와 일치해야 합니다:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "오늘 밤 주제는 인공지능 안전입니다.", "speech_metadata": { "speaker": "Alice", "style": "차분한 진행자" } },
        { "text": "결론부터 말씀드리면,<short pause>가장 큰 위험은 배포 단계에 있습니다.", "speech_metadata": { "speaker": "Bob", "style": "경쾌한 학자" } }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["AUDIO"],
    "speechConfig": {
      "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Puck" } }
    }
  }
}

음성 라이브러리 조회

GET https://api.gravitex.ai/v1beta/voices?model={model}

사용 가능한 음성(프리빌트 / 확장 음성 라이브러리)을 조회합니다. ?model=로 지정한 모델에 따라 채널이 라우팅됩니다. 조회는 과금되지 않습니다.

요청 파라미터

파라미터	필수	설명
`model`	예	모델 이름, 예: `gemini-3.8-flash-tts`
`language_code`	아니요	언어별 필터, 반복 가능, 예: `zh-CN`, `en-US`, `ar-EG`
`gender`	아니요	`female` / `male`
`pitch`	아니요	`low` / `medium` / `high`
`context`	아니요	적용 시나리오별 필터, 응답의 `context` 필드와 대응: `Content & Media`, `Conversational / Edu`, `Enterprise Agent`, `Growth & Marketing`, `Entertainment & Gaming`, `Wellness & Culture`
`type`	아니요	`prebuilt`(프리빌트) 등
`search`	아니요	음성 특징 자유 텍스트 검색, 예: `warm`
`page_size`	아니요	페이지 크기, 기본값 50
`page_token`	아니요	페이지 토큰, 이전 응답의 `next_page_token` 사용

요청 예시

curl -G "https://api.gravitex.ai/v1beta/voices?model=gemini-3.1-flash-tts-preview" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  --data-urlencode "language_code=zh-CN" \
  --data-urlencode "gender=female" \
  --data-urlencode "search=warm"

응답

{
  "voices": [
    {
      "id": "achernar",
      "type": "VOICE_TYPE_PREBUILT",
      "display_name": "Achernar",
      "language_code": "en-US",
      "region_code": "US",
      "accent": "General American",
      "persona": "Storyteller & Narrator",
      "context": "Content & Media",
      "gender": "female",
      "pitch": "PITCH_HIGH",
      "description": "Soft, calm, and soothing voice with a higher pitch. Recommended for quiet or personal storytelling."
    },
    {
      "id": "achird",
      "type": "VOICE_TYPE_PREBUILT",
      "display_name": "Achird",
      "language_code": "en-US",
      "region_code": "US",
      "accent": "General American",
      "persona": "Companion & Peer",
      "context": "Conversational / Edu",
      "gender": "male",
      "pitch": "PITCH_LOW",
      "description": "Friendly, approachable, and warm voice with a lower-middle pitch. Recommended for casual walkthroughs or vlogs."
    }
  ],
  "next_page_token": "achird|en-US"
}

필드	설명
`id`	음성 ID, `voiceName`에 입력하여 사용
`type`	음성 유형, 예: `VOICE_TYPE_PREBUILT`(프리빌트)
`display_name`	표시 이름
`language_code` / `region_code`	언어와 지역, 예: `en-US` / `US`
`accent`	억양, 예: `General American`
`persona`	페르소나, 예: `Storyteller & Narrator`, `High-Trust Advisor`
`context`	적용 시나리오
`gender`	`female` / `male`
`pitch`	`PITCH_HIGH` / `PITCH_MEDIUM` / `PITCH_LOW`
`description`	음성 설명
`next_page_token`	다음 페이지 토큰, 다음 요청의 `page_token`으로 전달. 더 이상 결과가 없으면 생략됨

음성 라이브러리는 ar-001(현대 표준 아랍어), ar-EG(이집트 아랍어) 등 지역 변형을 포함하여 130개 이상의 언어를 지원합니다.

모델 비교

모델	스타일 제어	멀티턴	출력 형식	컨텍스트 캐싱	언어
`gemini-3.8-flash-tts`	`speech_metadata` 구조화	✅	WAV	✅	130+
`gemini-3.1-flash-tts-preview`	본문 내 인라인 지시	❌	순수 PCM	❌	다국어

두 모델 모두 음성 라이브러리 조회(/v1beta/voices)와 프리빌트 음성(voiceName)을 지원합니다. 입력 / 출력 토큰 한도: 둘 다 8,192 / 16,384(출력 16,384 토큰은 약 11분 분량의 오디오).

과금

실제 사용량 기준으로 정산되며, 응답의 usageMetadata를 따릅니다:

항목	가격
입력(텍스트)	$0.50 / 1M tokens(`promptTokenCount`)
출력(오디오)	$9.00 / 1M tokens(`candidatesTokenCount`, 오디오 10초당 약 250 토큰)

음성 라이브러리 조회(/v1beta/voices)는 과금되지 않습니다.

자주 발생하는 오류

오류	원인 및 해결
`Multiturn chat is not enabled for this model`	3.1은 단일 턴만 지원합니다. 모든 내용을 하나의 user 턴으로 합치거나, 멀티턴이 필요하면 `gemini-3.8-flash-tts`로 변경하세요
`Invalid token`	API Key가 유효하지 않거나 `Authorization: Bearer` 헤더가 없음
`No available channel for model ...`	모델 이름 오류(예: `{model}` 플레이스홀더를 교체하지 않음) 또는 현재 그룹에 사용 가능한 채널이 없음
생성이 중단됨	출력이 16,384 토큰(약 11분)을 초과함. 나누어 합성하세요

API 문서

대화 및 텍스트

안전 및 오디오

이미지 시리즈

비디오 시리즈

텍스트 완성 및 임베딩

인터페이스 모듈

인증

Gemini 네이티브 형식 (TTS)

gemini-3.8-flash-tts

gemini-3.1-flash-tts-preview

응답

응답 처리

파라미터 설명

음성 라이브러리 조회

요청 파라미터

요청 예시

응답

모델 비교

과금

자주 발생하는 오류

관련 링크

​인증

​Gemini 네이티브 형식 (TTS)

​gemini-3.8-flash-tts

​gemini-3.1-flash-tts-preview

​응답

​응답 처리

​파라미터 설명

​음성 라이브러리 조회

​요청 파라미터

​요청 예시

​응답

​모델 비교

​과금

​자주 발생하는 오류

​관련 링크

인증

Gemini 네이티브 형식 (TTS)

gemini-3.8-flash-tts

gemini-3.1-flash-tts-preview

응답

응답 처리

파라미터 설명

음성 라이브러리 조회

요청 파라미터

요청 예시

응답

모델 비교

과금

자주 발생하는 오류

관련 링크