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

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

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