אתם יכולים ליצור קול בהתאמה אישית מתיאור בשפה טבעית באמצעות התכונה עיצוב קול. במקום לבחור קול מוכן מראש או להקליט אודיו להשוואה, אתם יוצרים קול על ידי תיאור הגיל, גוון הקול, המבטא והדיבור הבסיסי של הדמות. Voices API שומר את הקול בפרויקט ומחזיר מזהה voice_... שאפשר להשתמש בו שוב ושוב, ומעבירים אותו בבקשות ליצירת דיבור.
הקולות המעוצבים פועלים עם Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) ועם Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts).
איך עיצוב קולי עובד
- יצירת קול עם הנחיה: קוראים ל-method
createשל Voices API עםvoice.typeשמוגדר ל-VOICE_TYPE_PROMPTEDועםstoreשמוגדר ל-true. - קבלת מזהה קול ודגימה: Voices API יוצר את הקול, מאחסן אותו בפרויקט ומחזיר את המזהה שלו (לדוגמה,
voice_abc123...) בשדהidודגימה של הקול בשדהsample_audio. - יצירת דיבור: מעבירים את מזהה הקול ב-
speechConfig.voiceConfig.voiceכשמתקשרים אלgenerateContentאו אלstreamGenerateContent.
לפני שמתחילים
מבצעים את השלבים שבקטע לפני שמתחילים בדף Gemini TTS. Voices API זמין במיקום global דרך גרסת API v1beta1.
יצירת קול מעוצב
מגדירים את השדות הבאים בבקשה:
-
store: הערך צריך להיותtrue. קולות מעוצבים תמיד מאוחסנים בפרויקט. voice.type:VOICE_TYPE_PROMPTED.-
voice.prompted.input: תיאור של הקול בשפה טבעית. -
voice.display_name,voice.gender,voice.language_code: מטא-נתונים אופציונליים של הקול.
לא להגדיר את voice.model. בקשות שמגדירות מודל יחד עם store: true נכשלות עם השגיאה INVALID_ARGUMENT.
עיצוב קול יכול להימשך כמה שניות. בדוגמה של Python, הגדרנו את הזמן הקצוב לתפוגת הבקשה ל-60 שניות.
התשובה מכילה את השדות הבאים:
-
id: המזהה של הקול החדש. -
sample_audio: דגימה של הקול. השדהdataמכיל את האודיו בקידוד base64, והשדהmime_typeמכיל את שם הקידוד. לדוגמה,audio/l16; rate=24000; channels=1הוא PCM 16 ביט ללא כותרת ב-24 kHz, מונו. usage: מספר האסימונים שהבקשה השתמשה בהם. מידע נוסף מפורט במאמר בנושא תמחור.
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
אם הערך של sample_audio.mime_type הוא audio/l16, קובץ voice_sample.pcm מכיל אודיו PCM ב-16 ביט, 24kHz, מונו, ללא כותרת.
כדי לשמוע את הקול עם הטקסט שלכם, צריך ליצור דיבור באמצעות הקול כמו שמוסבר בקטע הבא.
יצירת דיבור באמצעות קול מעוצב
מעבירים את מזהה הקול ב-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
מחליפים את VOICE_ID במזהה הקול שהוחזר על ידי השיטה create.
ניהול הקולות השמורים
אתם יכולים להציג, לאחזר ולמחוק את הקולות ששמורים בפרויקט, כולל קולות מעוצבים וקולות משוכפלים שמורים.
השיטה list מחזירה את הקולות שמאוחסנים בפרויקט, ואחריהם את הקולות המובנים מראש ואת הקולות מספריית הקולות המורחבת. כדי להציג רק את הקולות ששמורים בפרויקט, מגדירים את המסנן type לערכים prompted ו-replicated, כמו בדוגמאות הבאות. בנוסף, השיטה get מחזירה את הדוגמה של קול מעוצב בשדה 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
מגבלות
- התוקף של קולות שנשמרו פג שנה אחרי השימוש האחרון בהם. יצירת דיבור בקול מסוים מאפסת את התקופה הזו, כך שקול שמשתמשים בו באופן קבוע לא יפוג. מוחקים קולות שכבר לא צריך.
- בקשות ליצירת קול כפופות למכסה של פרויקט לדקה. אם תחרגו מהמכסה, השיטה
createתחזיר את השגיאהRESOURCE_EXHAUSTED. צריך להמתין ולנסות שוב. מידע נוסף זמין במאמר בנושא מכסות ומגבלות מערכת.
תמחור
החיוב על יצירת קול מעוצב הוא לפי טוקנים של קלט טקסט וטוקנים של פלט אודיו, בהתאם לתעריפים של Gemini 3.8 Flash TTS. האסימונים של פלט האודיו כוללים את דגימת הקול שנוצרת על ידי Voices API. בשדה usage בתשובה create מופיעות שתי הספירות. לדוגמה, התיאור במשפט אחד ביצירת דוגמה משתמש בכ-220 אסימוני קלט ובכ-1,100 אסימוני פלט.
לא מתבצע חיוב על השיטות get, list ו-delete. החיוב על דיבור שנוצר באמצעות קול מעוצב הוא לפי התעריפים של המודל שאליו מתבצעת הקריאה.
במחירון של Gemini Enterprise תוכלו לעיין ברשימת התעריפים העדכניים לטוקנים.
שיטות מומלצות לכתיבת הנחיות
- הגדרת מאפיינים קבועים בתיאור הקול: כשיוצרים את הקול, מגדירים את הגיל, המגדר, גוון הקול, מרקם הקול והמבטא האזורי, ולא ב-
speech_metadata.style. - שימוש ב-
speech_metadata.styleלתיאור רגש במצב מסוים: אחרי שיוצרים את הקול, משתמשים בערכיstyleקצרים, כמו"whispered urgently"או"cheerful and energetic", כדי לכוון כל תור בלי לשנות את זהות הדובר. - היו ספציפיים ותמציתיים: תיאור ברור של משפט אחד או שניים, כמו "שדרנית ספורט אנרגטית וחדה בשנות ה-30 לחייה עם מבטא קל של המערב התיכון", יניב תוצאות עקביות יותר מאשר פסקה ארוכה או סותרת.
המאמרים הבאים
- לשכפל קול של דובר קיים באמצעות רפליקציה של קולות.
- מידע על סגנון ברמת התור, תגי שורה ודיאלוג עם כמה דוברים זמין במאמר יצירת דיבור באמצעות Gemini TTS.