Membuat suara kustom dengan desain suara

Anda dapat membuat suara kustom dari deskripsi bahasa alami menggunakan fitur desain suara. Alih-alih memilih suara bawaan atau merekam audio referensi, Anda membuat suara dengan mendeskripsikan usia karakter, timbre vokal, aksen, dan penyampaian dasar. Voices API menyimpan suara di project Anda dan menampilkan ID voice_... yang dapat digunakan kembali yang Anda teruskan dalam permintaan pembuatan ucapan.

Suara yang didesain berfungsi dengan Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) dan Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts).

Cara kerja desain suara

  1. Membuat suara yang dipandu: Panggil metode Voices API create dengan voice.type ditetapkan ke VOICE_TYPE_PROMPTED dan store ditetapkan ke true.
  2. Menerima ID suara dan sampel: Voices API membuat suara, menyimpannya di project Anda, dan menampilkan ID-nya (misalnya, voice_abc123...) di kolom id dan sampel suara di kolom sample_audio.
  3. Buat ucapan: Teruskan ID suara di speechConfig.voiceConfig.voice saat Anda memanggil generateContent atau streamGenerateContent.

Sebelum memulai

Selesaikan langkah-langkah di bagian Sebelum Anda memulai di halaman Gemini TTS. Voices API tersedia di lokasi global melalui versi v1beta1 API.

Membuat suara yang didesain

Tetapkan kolom berikut dalam permintaan:

  • store: Harus true. Suara yang didesain selalu disimpan di project Anda.
  • voice.type: VOICE_TYPE_PROMPTED.
  • voice.prompted.input: Deskripsi suara dalam bahasa alami.
  • voice.display_name, voice.gender, voice.language_code: Metadata opsional untuk suara.

Jangan setel voice.model. Permintaan yang menetapkan model bersama dengan store: true akan gagal dengan error INVALID_ARGUMENT.

Mendesain suara dapat memerlukan waktu beberapa detik. Contoh Python menetapkan waktu tunggu permintaan menjadi 60 detik.

Respons berisi kolom berikut:

  • id: ID suara baru.
  • sample_audio: Contoh suara. Kolom data menyimpan audio berenkode base64, dan kolom mime_type memberi nama encoding-nya. Misalnya, audio/l16; rate=24000; channels=1 adalah PCM 16-bit tanpa header pada 24 kHz, mono.

  • usage: Jumlah token yang digunakan permintaan. Untuk mengetahui informasi selengkapnya, lihat Harga.

Python

import base64
import wave

from google import genai

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

voice = client.voices.create(
    store=True,
    voice={
        "type": "VOICE_TYPE_PROMPTED",
        "display_name": "Warm British Astronomer",
        "gender": "male",
        "language_code": "en-GB",
        "prompted": {
            "input": (
                "A warm, thoughtful astronomer in his late 60s with a gentle"
                " British accent, speaking with quiet wonder."
            )
        },
    },
    timeout=60,
)

print(f"Created voice ID: {voice.id}")

# Save the voice sample. The SDK returns sample_audio.data as a base64
# string. Raw 16-bit PCM (audio/l16) needs a WAV header.
sample = base64.b64decode(voice.sample_audio.data)
if voice.sample_audio.mime_type.lower().startswith("audio/l16"):
    with wave.open("voice_sample.wav", "wb") as wf:
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)
        wf.writeframes(sample)
else:
    with open("voice_sample.wav", "wb") as f:
        f.write(sample)

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices \
  -d '{
    "store": true,
    "voice": {
      "type": "VOICE_TYPE_PROMPTED",
      "displayName": "Warm British Astronomer",
      "gender": "male",
      "languageCode": "en-GB",
      "prompted": {
        "input": "A warm, thoughtful astronomer in his late 60s with a gentle British accent, speaking with quiet wonder."
      }
    }
  }' > created_voice.json

# Print the voice ID and the encoding of the voice sample.
jq -r '.id, .sample_audio.mime_type' created_voice.json

# Decode the voice sample.
jq -r '.sample_audio.data' created_voice.json | base64 --decode > voice_sample.pcm

Jika sample_audio.mime_type adalah audio/l16, file voice_sample.pcm berisi audio PCM 16-bit tanpa header pada 24 kHz, mono.

Untuk mendengar suara dengan teks Anda sendiri, buat ucapan dengan suara tersebut seperti yang ditunjukkan di bagian berikutnya.

Membuat ucapan dengan suara yang dirancang

Teruskan ID suara di speechConfig.voiceConfig.voice:

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": (
                "Look out past the rings of Saturn. Those faint photons left"
                " their source millions of years ago."
            ),
            "speech_metadata": {"style": "reflective and awe-inspired"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {"voice_config": {"voice": "VOICE_ID"}},
    },
)

# The SDK has already decoded the base64 audio, so inline_data.data is a
# complete WAV file by default.
with open("designed_voice.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": "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
        "speechMetadata": {"style": "reflective and awe-inspired"}
      }]
    }],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": {"voice": "VOICE_ID"}
      }
    }
  }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 --decode > designed_voice.wav

Ganti VOICE_ID dengan ID suara yang ditampilkan oleh metode create.

Mengelola suara yang disimpan

Anda dapat mencantumkan, mendapatkan, dan menghapus suara yang disimpan di project Anda, termasuk suara yang didesain dan suara replika yang disimpan. Metode list menampilkan suara yang disimpan dalam project Anda, diikuti dengan suara bawaan dan Extended Voice Library. Untuk mencantumkan hanya suara yang disimpan di project Anda, tetapkan filter type ke prompted dan replicated, seperti yang dilakukan contoh berikut. Metode get juga menampilkan contoh suara yang dirancang di kolom sample_audio.

Python

from google import genai

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

# List the voices stored in your project.
for voice in client.voices.list(type_=["prompted", "replicated"]).voices or []:
    print(voice.id, voice.display_name, voice.type)

# Get a voice by ID.
voice = client.voices.get(id="VOICE_ID")

# Delete a voice.
client.voices.delete(id="VOICE_ID")

REST

# List the voices stored in your project.
curl -G \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices \
  --data-urlencode "type=prompted" \
  --data-urlencode "type=replicated"

# Get a voice by ID.
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices/VOICE_ID

# Delete a voice.
curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices/VOICE_ID

Batas

  • Masa berlaku suara tersimpan akan berakhir satu tahun setelah terakhir digunakan. Pembuatan ucapan dengan suara akan memulai ulang periode ini, sehingga suara yang Anda gunakan secara rutin tidak akan berakhir. Hapus suara yang tidak lagi Anda perlukan.
  • Permintaan pembuatan suara tunduk pada kuota per project per menit. Jika Anda melampauinya, metode create akan menampilkan error RESOURCE_EXHAUSTED. Tunggu, lalu coba lagi. Untuk mengetahui informasi selengkapnya, lihat Kuota dan batas sistem.

Harga

Pembuatan suara yang dirancang ditagih sebagai token input teks dan token output audio dengan tarif TTS kilat Gemini 3.8. Token output audio mencakup contoh suara yang dihasilkan Voices API. Kolom usage dalam respons create melaporkan kedua jumlah tersebut. Misalnya, deskripsi satu kalimat dalam buat contoh menggunakan sekitar 220 token input dan sekitar 1.100 token output.

Metode get, list, dan delete tidak ditagih. Ucapan yang Anda hasilkan dengan suara yang dirancang ditagih sesuai tarif model yang Anda panggil.

Untuk mengetahui tarif token, lihat Harga Gemini Enterprise.

Praktik terbaik perintah

  • Masukkan ciri permanen dalam deskripsi suara: Tentukan usia, gender, timbre, tekstur vokal, dan aksen regional saat Anda membuat suara, bukan di speech_metadata.style.
  • Gunakan speech_metadata.style untuk emosi situasional: Setelah Anda membuat suara, gunakan nilai style pendek, seperti "whispered urgently" atau "cheerful and energetic", untuk mengarahkan setiap giliran tanpa mengubah identitas penutur.
  • Buat perintah yang spesifik dan ringkas: Deskripsi yang jelas dalam satu atau dua kalimat, seperti "Seorang penyiar olahraga yang bersemangat dan berwibawa berusia 30-an dengan sedikit aksen Midwestern", akan menghasilkan hasil yang lebih konsisten daripada paragraf yang panjang atau bertentangan.

Langkah berikutnya