Membuat ucapan dengan Gemini TTS

Model text-to-speech (TTS) Gemini mengonversi teks menjadi audio satu penutur atau multi-penutur. Anda dapat mengontrol gaya, aksen, kecepatan, dan nada audio dengan metadata giliran terstruktur (speech_metadata) dan tag vokal inline.

Halaman ini menunjukkan cara membuat ucapan dengan model berikut menggunakan metode generateContent dan streamGenerateContent Gemini Enterprise API:

Model TTS disesuaikan untuk pembacaan teks yang tepat dengan kontrol terperinci atas gaya dan suara, seperti narasi, buku audio, dan respons agen suara. Untuk percakapan interaktif secara real-time dengan input dan output audio, gunakan Live API.

Jika Anda menggunakan model Gemini TTS yang lebih lama, seperti gemini-3.1-flash-tts-preview, lihat panduan migrasi.

Model yang didukung

Model Satu penutur Multi-penutur Streaming Desain suara Replikasi suara
Gemini 3.8 Flash TTS (gemini-3.8-flash-tts)
Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts)
Pratinjau Gemini 3.1 Flash TTS (gemini-3.1-flash-tts-preview)
Gemini 2.5 Pro TTS (gemini-2.5-pro-tts)
Gemini 2.5 Flash TTS (gemini-2.5-flash-tts)

Contoh dan fitur di halaman ini berlaku untuk model TTS Gemini 3.8. Untuk model sebelumnya, lihat Gemini-TTS di dokumentasi Text-to-SpeechGoogle Cloud .

Kapan model tertentu sebaiknya digunakan

Kedua model TTS Gemini 3.8 memiliki skema permintaan dan format perintah yang sama, sehingga Anda dapat beralih di antara keduanya dengan mengubah ID model:

  • Gunakan Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) jika kesetiaan akustik, akting yang bernuansa, dan kontrol ekspresif menjadi prioritas utama. Fitur ini cocok untuk pekerjaan kreatif tingkat studio, dialog multi-pembicara yang kompleks, tag vocal-burst yang sering, pelafalan yang sulit, dialek regional atau minoritas, dan narasi panjang yang memerlukan suara dan nada ruang yang stabil.
  • Gunakan Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) untuk beban kerja produksi yang cepat dan hemat biaya. Model ini adalah pengganti gemini-3.1-flash-tts-preview yang direkomendasikan, dan cocok untuk produksi batch bervolume tinggi, cascade agen suara percakapan, fitur baca lisan, replikasi suara, dan ucapan speaker tunggal sehari-hari dalam bahasa utama.

Sebelum memulai

  1. Siapkan project dan aktifkan Gemini Enterprise API.
  2. Konfigurasi Kredensial Default Aplikasi untuk lingkungan pengembangan Anda.
  3. Untuk menggunakan contoh Python, instal Google Gen AI SDK versi 2.25.0 atau yang lebih baru:

    pip install --upgrade "google-genai>=2.25.0"
    

Model TTS Gemini 3.8 tersedia di lokasi global. Kirim permintaan ke endpoint aiplatform.googleapis.com.

TTS satu penutur

Untuk mengonversi teks menjadi audio satu penutur, teruskan transkrip kata demi kata di parts[].text, tambahkan gaya tingkat giliran opsional di parts[].speech_metadata, dan tetapkan suara di speechConfig.voiceConfig.voice. Kolom voice menerima nama suara bawaan, ID suara Extended Voice Library, atau ID (voice_...) suara yang didesain atau direplikasi (atau kunci voicekey_... tanpa status opsional).

Secara default, permintaan unary menampilkan file WAV lengkap (PCM 16-bit, 24 kHz, mono), sehingga Anda dapat menulis byte audio langsung ke file .wav. Permintaan streaming menampilkan potongan PCM mentah. Untuk mengetahui detail dan encoding lainnya, lihat Format output audio.

Python

from google import genai

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

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {"style": "cheerful and friendly"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {"voice_config": {"voice": "Kore"}},
    },
)

# The SDK has already decoded the base64 audio, so inline_data.data is a
# complete WAV file by default.
with open("out.wav", "wb") as f:
    f.write(response.candidates[0].content.parts[0].inline_data.data)

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Have a wonderful day!",
        "speechMetadata": {"style": "cheerful and friendly"}
      }]
    }],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": {"voice": "Kore"}
      }
    }
  }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 --decode > out.wav

TTS streaming satu penutur

Untuk menerima audio saat model masih menyintesisnya, gunakan metode streamGenerateContent. Respons streaming menampilkan potongan PCM 16-bit mentah tanpa header (24 kHz, mono), sehingga Anda dapat meneruskan setiap potongan ke pemutar, soket, atau pipeline audio lain saat tiba. Dalam contoh Python berikut, fungsi emit_audio menggantikan tujuan tersebut.

Python

from google import genai

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

def emit_audio(pcm: bytes) -> None:
    """Sends a chunk of raw 16-bit PCM audio (24 kHz, mono) downstream."""
    # Replace with your audio destination, such as a player, a WebSocket,
    # or a telephony stream.
    print(f"Received {len(pcm)} bytes of audio")

response_stream = client.models.generate_content_stream(
    model="gemini-3.8-flash-lite-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {"style": "cheerful and friendly"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {"voice_config": {"voice": "Kore"}},
    },
)

for chunk in response_stream:
    if not chunk.candidates or not chunk.candidates[0].content:
        continue
    for part in chunk.candidates[0].content.parts or []:
        if part.inline_data and part.inline_data.data:
            emit_audio(part.inline_data.data)

REST

curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-lite-tts:streamGenerateContent?alt=sse" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Have a wonderful day!",
        "speechMetadata": {"style": "cheerful and friendly"}
      }]
    }],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": {"voice": "Kore"}
      }
    }
  }' | sed -n 's/^data: //p' \
    | jq -r '.candidates[0].content.parts[0].inlineData.data // empty' \
    | while read -r chunk; do echo "$chunk" | base64 --decode; done > streamed.pcm

File streamed.pcm berisi audio PCM 16-bit mentah pada 24 kHz, mono.

TTS multi-penutur

Untuk dialog antara dua pembicara, konfigurasi kedua pembicara di speechConfig.multiSpeakerVoiceConfig.speakerVoiceConfigs. Kemudian, teruskan setiap giliran sebagai part terpisah, tetapkan speech_metadata.speaker di setiap giliran ke salah satu nama pembicara yang dikonfigurasi, dan tambahkan style tingkat giliran opsional.

Permintaan multi-speaker memerlukan tepat dua speaker.

Python

from google import genai

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

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [
            {
                "text": "How's it going today, Jane?",
                "speech_metadata": {"speaker": "Joe", "style": "cheerful and friendly"},
            },
            {
                "text": "Not too bad, how about you? Ready to test these new voices?",
                "speech_metadata": {"speaker": "Jane", "style": "calm and relaxed"},
            },
        ],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "multi_speaker_voice_config": {
                "speaker_voice_configs": [
                    {"speaker": "Joe", "voice_config": {"voice": "Puck"}},
                    {"speaker": "Jane", "voice_config": {"voice": "Kore"}},
                ]
            }
        },
    },
)

with open("dialogue.wav", "wb") as f:
    f.write(response.candidates[0].content.parts[0].inline_data.data)

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [
        {
          "text": "How'\''s it going today, Jane?",
          "speechMetadata": {"speaker": "Joe", "style": "cheerful and friendly"}
        },
        {
          "text": "Not too bad, how about you? Ready to test these new voices?",
          "speechMetadata": {"speaker": "Jane", "style": "calm and relaxed"}
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "multiSpeakerVoiceConfig": {
          "speakerVoiceConfigs": [
            {"speaker": "Joe", "voiceConfig": {"voice": "Puck"}},
            {"speaker": "Jane", "voiceConfig": {"voice": "Kore"}}
          ]
        }
      }
    }
  }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 --decode > dialogue.wav

TTS streaming multi-penutur

Permintaan multi-pembicara juga mendukung streaming. Gunakan permintaan yang sama seperti di TTS Multi-speaker dengan metode streamGenerateContent.

Python

from google import genai

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

def emit_audio(pcm: bytes) -> None:
    """Sends a chunk of raw 16-bit PCM audio (24 kHz, mono) downstream."""
    # Replace with your audio destination, such as a player, a WebSocket,
    # or a telephony stream.
    print(f"Received {len(pcm)} bytes of audio")

response_stream = client.models.generate_content_stream(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [
            {
                "text": "How's it going today, Jane?",
                "speech_metadata": {"speaker": "Joe", "style": "cheerful and friendly"},
            },
            {
                "text": "Not too bad, how about you? Ready to test these new voices?",
                "speech_metadata": {"speaker": "Jane", "style": "calm and relaxed"},
            },
        ],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "multi_speaker_voice_config": {
                "speaker_voice_configs": [
                    {"speaker": "Joe", "voice_config": {"voice": "Puck"}},
                    {"speaker": "Jane", "voice_config": {"voice": "Kore"}},
                ]
            }
        },
    },
)

for chunk in response_stream:
    if not chunk.candidates or not chunk.candidates[0].content:
        continue
    for part in chunk.candidates[0].content.parts or []:
        if part.inline_data and part.inline_data.data:
            emit_audio(part.inline_data.data)

REST

curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:streamGenerateContent?alt=sse" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [
        {
          "text": "How'\''s it going today, Jane?",
          "speechMetadata": {"speaker": "Joe", "style": "cheerful and friendly"}
        },
        {
          "text": "Not too bad, how about you? Ready to test these new voices?",
          "speechMetadata": {"speaker": "Jane", "style": "calm and relaxed"}
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "multiSpeakerVoiceConfig": {
          "speakerVoiceConfigs": [
            {"speaker": "Joe", "voiceConfig": {"voice": "Puck"}},
            {"speaker": "Jane", "voiceConfig": {"voice": "Kore"}}
          ]
        }
      }
    }
  }' | sed -n 's/^data: //p' \
    | jq -r '.candidates[0].content.parts[0].inlineData.data // empty' \
    | while read -r chunk; do echo "$chunk" | base64 --decode; done > dialogue_streamed.pcm

File dialogue_streamed.pcm berisi audio PCM 16-bit mentah pada 24 kHz, mono.

Mengontrol gaya ucapan dengan metadata dan tag

Model Gemini 3.8 TTS memperlakukan kolom text sebagai transkrip kata demi kata. Petunjuk yang ditulis dalam teks, seperti "Say cheerfully: Hello!" atau "Speaker 1: Hello!", mungkin dibacakan. Untuk mengontrol pengiriman, pisahkan petunjuk menurut cakupan:

  • Penyampaian tingkat giliran yang berkelanjutan (speech_metadata.style): Masukkan emosi, gaya penyampaian, prosodi, kecepatan, dan volume yang berlaku untuk seluruh giliran dalam speech_metadata.style. Misalnya, "style": "whispered urgently", "style": "out of breath", atau "style": "warm and enthusiastic".
  • Peristiwa point-in-time (tag inline): Masukkan suara vokal non-ucapan sesaat dan jeda di dalam transkrip dalam tanda kurung sudut. Misalnya, "Wait... <short pause> did you hear that? <sigh>" atau "Excuse me <cough> as I was saying...".

Untuk panduan selengkapnya, lihat panduan perintah.

Pilihan suara

Model Gemini 3.8 TTS mendukung empat cara untuk memilih atau membuat suara:

  1. Suara bawaan: 30 suara pilihan.
  2. Perpustakaan Suara yang Diperluas: Lebih dari 2.000 suara preset pilihan yang mencakup berbagai bahasa, aksen regional, dan persona karakter.
  3. Desain suara: Buat suara kustom dari deskripsi bahasa alami dengan metode Voices API create (client.voices.create() di Google Gen AI SDK, atau POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices). Tetapkan type ke VOICE_TYPE_PROMPTED dan store ke true. Respons menampilkan ID voice_... yang disimpan dan sampel suara.
  4. Replikasi suara: Mereplikasi suara pembicara dari audio referensi dan persetujuan dengan metode create yang sama. Tetapkan type ke VOICE_TYPE_REPLICATED. Dengan store: true, respons akan menampilkan ID voice_... yang disimpan. Dengan store: false, fungsi ini menampilkan kunci voicekey_... stateless.

Batas suara kustom dan TTL

Jenis suara Mode penyimpanan Pengelolaan Akhir masa berlaku
Suara tersimpan (voice_..., didesain atau direplikasi) store: true Metode list, get, dan delete Voices API 1 tahun setelah penggunaan terakhir
Kunci replikasi suara (voicekey_...) store: false Dikelola oleh aplikasi Anda. Google tidak menyimpan kunci. 7 hari setelah pembuatan

Membuat ucapan dengan suara tersimpan akan memulai ulang periode retensi satu tahunnya, sehingga suara yang sering Anda gunakan tidak akan berakhir. Permintaan pembuatan suara tunduk pada kuota per project per menit. Jika Anda melampauinya, metode create akan menampilkan error RESOURCE_EXHAUSTED. Untuk mengetahui informasi selengkapnya, lihat Kuota dan batas sistem.

Suara bawaan

Daftar berikut menunjukkan setiap nama suara bawaan dan karakteristiknya:

  • Achernar: Lembut
  • Achird: Ramah
  • Algenib: Berpasir
  • Algieba: Lancar
  • Alnilam: Tegas
  • Aoede: Ringan
  • Autonoe: Ceria
  • Callirrhoe: Santai
  • Charon: Informatif
  • Despina: Halus
  • Enceladus: Berdesah
  • Erinome: Jelas
  • Fenrir: Antusias
  • Gacrux: Dewasa
  • Iapetus: Jelas
  • Kore: Tegas
  • Laomedeia: Riang
  • Leda: Muda
  • Orus: Tegas
  • Puck: Ceria
  • Pulcherrima: Spontan
  • Rasalgethi: Informatif
  • Sadachbia: Bersemangat
  • Sadaltager: Berpengetahuan
  • Schedar: Genap
  • Sulafat: Hangat
  • Umbriel: Santai
  • Vindemiatrix: Tenang
  • Zephyr: Ceria
  • Zubenelgenubi: Kasual

Koleksi Suara yang Diperluas

Selain 30 suara bawaan, Extended Voice Library menyediakan lebih dari 2.000 suara preset pilihan dalam berbagai bahasa, aksen regional, persona karakter, dan kasus penggunaan seperti buku audio, agen percakapan, dan berita. Untuk menggunakan suara library, teruskan ID-nya di speechConfig.voiceConfig.voice, dengan cara yang sama seperti saat Anda meneruskan nama suara bawaan.

Untuk menjelajahi library, panggil metode Voices API list (ListVoices). Metode ini akan menampilkan suara kustom yang disimpan di project Anda, diikuti dengan suara bawaan dan Extended Voice Library. Setiap suara library mencakup id dan metadata seperti language_code, accent, gender, pitch, persona, dan description. Untuk mempersempit hasil, gunakan filter berikut:

  • type: Sumber suara: prebuilt untuk suara bawaan dan suara library, prompted untuk suara yang didesain, atau replicated untuk suara yang direplikasi. Jika Anda meneruskan lebih dari satu nilai, metode ini akan menampilkan suara yang cocok dengan salah satu nilai tersebut.
  • search: Teks yang akan dicocokkan, tanpa membedakan huruf besar/kecil, dengan nama tampilan dan deskripsi setiap suara.

Contoh berikut menelusuri suara narator di library:

Python

from google import genai

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

response = client.voices.list(type_=["prebuilt"], search="narrator", page_size=50)
for voice in response.voices or []:
    print(voice.id, voice.language_code, voice.gender, voice.description)

REST

curl -G \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices \
  --data-urlencode "type=prebuilt" \
  --data-urlencode "search=narrator" \
  --data-urlencode "pageSize=50"

Metode list menampilkan hingga 50 suara per halaman. Untuk mendapatkan halaman berikutnya, teruskan nilai next_page_token dari respons sebagai parameter page_token.

Format output audio

Encoding audio default bergantung pada metode:

  • Permintaan unary (generateContent) menampilkan file WAV lengkap (audio/wav) dengan header RIFF: PCM 16-bit, 24 kHz, mono.
  • Permintaan streaming (streamGenerateContent) menampilkan headerless raw chunk PCM little-endian bertanda 16-bit (audio/l16) pada 24 kHz, mono.

Untuk meminta encoding yang berbeda, tetapkan generationConfig.responseFormat ke format audio. Model TTS Gemini 3.8 mendukung nilai mimeType berikut:

Nilai mimeType Format Deskripsi
AUDIO_WAV (default unary) WAV (audio/wav) File WAV lengkap dengan header RIFF (PCM 16-bit, 24 kHz, mono).
AUDIO_L16 (streaming default) PCM Linear (audio/l16) PCM little-endian bertanda 16-bit mentah tanpa header. Gunakan untuk streaming, pipeline audio kustom, atau menggabungkan klip multi-giliran.
AUDIO_MULAW μ-law (audio/mulaw) Audio companded μ-law G.711 (8 kHz, mono), yang umum digunakan dalam telepon di Amerika Utara dan Jepang.
AUDIO_ALAW A-law (audio/alaw) Audio companded A-law G.711 (8 kHz, mono), yang umum digunakan dalam telepon Eropa dan internasional.

Model mengabaikan kolom sampleRate. Output PCM Linear dan WAV adalah 24 kHz, dan output μ-law dan A-law adalah 8 kHz, terlepas dari kecepatan dalam respons mimeType. Lakukan pengambilan sampel ulang pada output di klien jika pipeline Anda memerlukan frekuensi sampel yang berbeda.

Contoh berikut meminta output hukum μ untuk pipeline telepon. Google Gen AI SDK for Python tidak mengekspos responseFormat di GenerateContentConfig, sehingga contoh Python meneruskannya di isi permintaan dengan http_options.extra_body.

Python

from google import genai

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

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{"role": "user", "parts": [{"text": "Have a wonderful day!"}]}],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {"voice_config": {"voice": "Kore"}},
        "http_options": {
            "extra_body": {
                "generationConfig": {
                    "responseFormat": [{"audio": {"mimeType": "AUDIO_MULAW"}}]
                }
            }
        },
    },
)

# The response is headerless μ-law audio at 8 kHz, mono.
with open("out.mulaw", "wb") as f:
    f.write(response.candidates[0].content.parts[0].inline_data.data)

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Have a wonderful day!"}]}],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "responseFormat": [{"audio": {"mimeType": "AUDIO_MULAW"}}],
      "speechConfig": {
        "voiceConfig": {"voice": "Kore"}
      }
    }
  }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 --decode > out.mulaw

Bahasa yang didukung

Model TTS Gemini 3.8 mendeteksi bahasa input secara otomatis. Gemini 3.8 Flash TTS mendukung 130 bahasa, dan Gemini 3.8 Flash-Lite TTS mendukung 101 bahasa:

Batasan

  • Model TTS menerima input hanya teks dan menampilkan output hanya audio.
  • Permintaan multi-speaker memerlukan tepat dua speaker. Untuk menggabungkan suara yang didesain (voice_...) atau direplikasi (voice_... atau voicekey_...) dalam dialog multi-karakter, atau untuk menggunakan lebih dari dua speaker, sintesis setiap giliran speaker secara terpisah dan gabungkan audio. Minta output AUDIO_L16 untuk setiap giliran, atau hapus header WAV dari setiap klip sebelum Anda menggabungkan klip.
  • Model hanya tersedia di lokasi global.
  • Petunjuk sistem tidak didukung.
  • Anda tidak dapat menyetel frekuensi sampling output. Output MP3 dan Ogg Opus tidak didukung.

Langkah berikutnya