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, timbre vokal, aksen, dan penyampaian dasar karakter. Voices API menyimpan suara dalam 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
- Membuat suara yang diminta: Panggil metode
createVoices API denganvoice.typeditetapkan keVOICE_TYPE_PROMPTEDdanstoreditetapkan ketrue. - Menerima ID suara dan sampel: Voices API menghasilkan suara,
menyimpannya di project Anda, dan menampilkan ID-nya (misalnya,
voice_abc123...) di kolomiddan sampel suara di kolomsample_audio. - Membuat ucapan: Teruskan ID suara di
speechConfig.voiceConfig.voicesaat Anda memanggilgenerateContentataustreamGenerateContent.
Sebelum memulai
Selesaikan langkah-langkah di bagian
Sebelum memulai
di halaman Gemini TTS. Voices API tersedia di lokasi global
melalui versi API v1beta1.
Membuat suara yang didesain
Tetapkan kolom berikut dalam permintaan:
store: Harustrue. 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 ke 60 detik.
Respons berisi kolom berikut:
id: ID suara baru.sample_audio: Contoh suara. Kolomdatamenyimpan audio berenkode base64, dan kolommime_typememberi nama encoding-nya. Misalnya,audio/l16; rate=24000; channels=1adalah 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 mendengarkan suara dengan teks Anda sendiri, buat ucapan dengan suara tersebut seperti yang ditunjukkan di bagian berikutnya.
Membuat ucapan dengan suara yang didesain
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 dalam project Anda, termasuk suara yang didesain dan suara replika yang disimpan.
Metode list menampilkan suara yang disimpan di 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 didesain 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 yang disimpan akan berakhir satu tahun setelah terakhir kali digunakan. Membuat ucapan dengan suara akan memulai ulang periode ini, sehingga suara yang Anda gunakan secara rutin tidak akan habis masa berlakunya. Hapus suara yang tidak lagi Anda perlukan.
- Permintaan pembuatan suara tunduk pada kuota per project, per menit. Jika
Anda melampauinya, metode
createakan menampilkan errorRESOURCE_EXHAUSTED. Tunggu dan coba lagi. Untuk mengetahui informasi selengkapnya, lihat Kuota dan batas sistem.
Harga
Pembuatan suara yang didesain ditagih sebagai token input teks dan token output audio dengan tarif TTS Gemini 3.8 Flash. Token output audio mencakup
sampel suara yang dihasilkan Voices API. Kolom usage dalam respons create
melaporkan kedua jumlah tersebut. Misalnya, deskripsi satu kalimat dalam
contoh pembuatan menggunakan sekitar 220 token input dan sekitar 1.100 token
output.
Metode get, list, dan delete tidak akan ditagih. Ucapan yang Anda buat
dengan suara yang didesain akan ditagih sesuai tarif model yang Anda panggil.
Untuk mengetahui tarif token, lihat Harga Gemini Enterprise.
Praktik terbaik dalam memberikan perintah
- Masukkan karakteristik 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.styleuntuk emosi situasional: Setelah Anda membuat suara, gunakan nilaistylesingkat, seperti"whispered urgently"atau"cheerful and energetic", untuk mengarahkan setiap giliran tanpa mengubah identitas pembicara. - Buat deskripsi yang spesifik dan ringkas: Deskripsi yang jelas dalam satu atau dua kalimat, seperti "Seorang komentator olahraga yang energik dan tegas berusia 30-an dengan sedikit aksen Midwestern", akan menghasilkan hasil yang lebih konsisten daripada paragraf yang panjang atau kontradiktif.
Langkah berikutnya
- Mereplikasi suara pembicara yang ada dengan Replikasi suara.
- Pelajari gaya tingkat giliran, tag inline, dan dialog multi-pembicara di Membuat ucapan dengan Gemini TTS.