Gemini 3.8 TTS로 이전

이 페이지에서는 gemini-3.1-flash-tts-preview, gemini-2.5-flash-tts, gemini-2.5-pro-tts, gemini-2.5-flash-lite-preview-tts과 같은 이전 Gemini TTS 모델에서 Gemini 3.8 Flash TTS(gemini-3.8-flash-tts) 및 Gemini 3.8 Flash-Lite TTS(gemini-3.8-flash-lite-tts)로 이동하는 방법을 설명합니다. 이전 모델은 Google Cloud텍스트 음성 변환 문서의 Gemini-TTS에 설명되어 있습니다.

교체 모델 선택

  • Gemini 3.8 Flash-Lite TTS는 gemini-3.1-flash-tts-preview를 대체하는 것이 좋습니다. 대량 생산, 음성 에이전트, 읽어주기 기능, 일상적인 단일 스피커 음성에 적합합니다.
  • Gemini 3.8 Flash TTS는 플래그십 모델입니다. 오디오북, 스튜디오 내레이션 등 음성 충실도, 연기 뉘앙스, 다중 화자 대화, 방언 지원이 가장 중요한 경우에 선택하세요.

두 모델 모두 동일한 요청 스키마를 사용하므로 모델 ID를 변경하여 모델 간에 전환할 수 있습니다. 비교는 어떤 모델을 사용해야 하나요?를 참고하세요.

변경사항 요약

영역 이전 Gemini TTS 모델 Gemini 3.8 TTS 모델
API Cloud Text-to-Speech API 또는 Gemini Enterprise API Gemini Enterprise API만 (generateContent 및 streamGenerateContent)
위치 global 및 리전 엔드포인트 global만 해당
스타일 방향 텍스트 ("Say the following in a curious way: ...") 또는 Cloud Text-to-Speech prompt 필드에 작성됨 각 파트의 speech_metadata.style
다중 화자 대화 하나의 텍스트 블록에 있는 화자 접두사 또는 Cloud Text-to-Speech multiSpeakerMarkup speech_metadata.speaker를 사용한 턴당 한 부분
인라인 보컬 태그 대괄호(예: [sigh]) 꺾쇠 괄호(예: <sigh>)
음성 선택 prebuiltVoiceConfig.voiceName voiceConfig.voice: 설계된 음성 ID와 음성 복제 키도 허용합니다. prebuiltVoiceConfig.voiceName는 사전 빌드된 음성에서 계속 작동합니다.
커스텀 음성 replicatedVoiceConfig의 인라인 참조 오디오 Voices API를 통한 음성 디자인 및 음성 복제
기본 출력 (Gemini Enterprise API) 원시 16비트 PCM, 24kHz, 모노 단항 요청: 완전한 WAV 파일 (16비트 PCM, 24kHz, 모노) 스트리밍 요청: 원시 16비트 PCM, 변경되지 않음 responseFormat를 사용하여 다른 인코딩을 요청할 수 있습니다.
temperature, topP, topK 무시됨 INVALID_ARGUMENT 오류로 거부됨

요청 업데이트

  1. 스타일 지침을 speech_metadata.style로 이동: Gemini 3.8 TTS 모델은 text를 그대로 읽으므로 텍스트에 작성된 지침이 소리 내어 말해질 수 있습니다. 지속적인 연기, 어조, 운율, 페이싱 방향을 speech_metadata.style에 넣습니다.
  2. 대화 턴당 한 부분 사용: 다중 화자 대화의 경우 각 턴을 별도의 part로 전달하고 모든 턴에서 speech_metadata.speaker을 multiSpeakerVoiceConfig의 화자 중 하나로 설정합니다.
  3. 대괄호 태그를 꺾쇠괄호 태그로 바꾸기: 특정 시점의 음성 이벤트에만 꺾쇠괄호(예: <sigh>, <laugh>, <short pause>)를 사용합니다. '음'과 같은 말실수를 스크립트에 직접 작성합니다.
  4. 사전에 페르소나 설계: 긴 '오디오 프로필' 또는 '감독의 메모' 프롬프트를 음성 설계에서 만든 음성으로 대체하고 style을 짧게 유지하거나 비워 둡니다.
  5. 지원되지 않는 매개변수 삭제: 요청에서 temperature, topP, topK, candidateCount, systemInstruction를 삭제합니다.
  6. 단항 요청에서 WAV 출력 처리: 이제 단항 요청은 원시 PCM 대신 완전한 WAV 파일을 반환합니다. 코드에서 WAV 헤더를 추가하거나 클립을 연결하는 경우 헤더 단계를 삭제하거나 generationConfig.responseFormat를 AUDIO_L16로 설정하여 원시 PCM 출력을 유지하세요.
  7. Voices API로 복제된 음성 다시 만들기: replicatedVoiceConfig의 인라인 참조 오디오는 지원되지 않습니다. Voices API로 저장된 음성 또는 음성 복제 키를 만들고 voiceConfig.voice에 전달합니다. 자세한 내용은 음성 복제를 참고하세요.

프롬프트 작성에 관한 자세한 내용은 프롬프트 가이드를 참고하세요.

예

다음 예시에서는 gemini-3.1-flash-tts-preview 요청과 이에 상응하는 Gemini 3.8 TTS 요청을 보여줍니다.

Gemini 3.8 이전

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-3.1-flash-tts-preview",
    contents="Say the following in a curious way: OK, so... tell me about this [uhm] AI thing.",
    config=types.GenerateContentConfig(
        response_modalities=["AUDIO"],
        speech_config=types.SpeechConfig(
            language_code="en-US",
            voice_config=types.VoiceConfig(
                prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
            ),
        ),
    ),
)

Gemini 3.8 이상

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-3.8-flash-lite-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "OK, so... uhm, tell me about this AI thing.",
            "speech_metadata": {"style": "curious"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "language_code": "en-US",
            "voice_config": {"voice": "Kore"},
        },
    },
)

두 응답 모두 response.candidates[0].content.parts[0].inline_data.data에 오디오를 반환합니다. 이전 모델은 원시 16비트 PCM 오디오 (24kHz, 모노)를 반환하고 Gemini 3.8 TTS 모델은 완전한 WAV 파일을 반환합니다.

Cloud Text-to-Speech API에서 이전

Cloud Text-to-Speech API(texttospeech.googleapis.com)를 통해 Gemini TTS를 호출하는 경우 aiplatform.googleapis.com의 generateContent 메서드로 요청을 전송하세요. 다음 표에서는 Cloud Text-to-Speech 요청 필드를 Gemini Enterprise API 요청 필드에 매핑합니다.

Cloud Text-to-Speech API (text:synthesize) Gemini Enterprise API (generateContent)
input.text contents[].parts[].text
input.prompt contents[].parts[].speechMetadata.style
input.multiSpeakerMarkup.turns[](speaker, text) 턴당 한 부분, text 및 speechMetadata.speaker
voice.modelName 요청 URL의 모델 ID
voice.name generationConfig.speechConfig.voiceConfig.voice
voice.languageCode generationConfig.speechConfig.languageCode
voice.multiSpeakerVoiceConfig.speakerVoiceConfigs[](speakerAlias, speakerId) generationConfig.speechConfig.multiSpeakerVoiceConfig.speakerVoiceConfigs[](speaker, voiceConfig.voice)
audioConfig.audioEncoding: LINEAR16 generationConfig.responseFormat[].audio.mimeType: AUDIO_WAV (단항 요청의 기본값)
audioConfig.audioEncoding: PCM AUDIO_L16 (스트리밍 요청의 기본값)
audioConfig.audioEncoding: MULAW 또는 ALAW AUDIO_MULAW 또는 AUDIO_ALAW
audioConfig.audioEncoding: MP3 또는 OGG_OPUS 지원되지 않음. 클라이언트에서 오디오를 인코딩합니다.
audioConfig.sampleRateHertz 지원되지 않음. 출력 샘플링 레이트는 오디오 출력 형식을 참고하세요.

Cloud Text-to-Speech API는 audioContent에 base64 인코딩된 오디오를 반환합니다. Gemini Enterprise API는 candidates[0].content.parts[0].inlineData.data에 이를 반환합니다.

다음 단계