יצירת קול בהתאמה אישית באמצעות עיצוב קול

אתם יכולים ליצור קול בהתאמה אישית מתיאור בשפה טבעית באמצעות התכונה עיצוב קול. במקום לבחור קול מוגדר מראש או להקליט קובץ עזר, אתם יכולים ליצור קול על ידי תיאור הגיל, גוון הקול, המבטא וסגנון הדיבור של הדמות. ‫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).

איך פועל עיצוב הקול

  1. יצירת קול באמצעות הנחיה: מפעילים את ה-method‏ create של Voices API, כש-voice.type מוגדר ל-VOICE_TYPE_PROMPTED ו-store מוגדר ל-true.
  2. קבלת מזהה קול ודגימה: Voices API יוצר את הקול, שומר אותו בפרויקט ומחזיר את המזהה שלו (לדוגמה, voice_abc123...) בשדה id ודגימה של הקול בשדה sample_audio.
  3. יצירת דיבור: מעבירים את מזהה הקול ב-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 ביט ללא כותרת ב-24kHz, מונו.
  • ‫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 מחזירה את הקולות ששמורים בפרויקט, ואחריהם את הקולות המובנים מראש ואת הקולות מ-Extended Voice Library. כדי להציג רק את הקולות ששמורים בפרויקט, מגדירים את המסנן 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 לחייה עם מבטא קל של המערב התיכון", מניב תוצאות עקביות יותר מאשר פסקה ארוכה או סותרת.

המאמרים הבאים