יצירת המרת טקסט לדיבור (TTS)

‫Gemini API יכול להמיר קלט טקסט לאודיו של דובר יחיד או של כמה דוברים באמצעות יכולות המרת טקסט לדיבור (TTS) של Gemini. הפקת טקסט לדיבור היא ניתנת לשליטה, כלומר אפשר לשלב מטא-נתונים מובְנים של תור (speech_metadata) ותגי קול מוטבעים כדי להגדיר את הסגנון, המבטא, הקצב והטון של האודיו.

יכולת ה-TTS שונה מיצירת דיבור שמתבצעת באמצעות Live API, שנועד לאודיו אינטראקטיבי ולא מובנה, ולקלט ולפלט מולטי-מודאליים. ‫Live API מתאים במיוחד לשיחות דינמיות, אבל TTS דרך Gemini API מתאים לתרחישים שבהם צריך להקריא טקסט מדויק עם שליטה מדויקת בסגנון ובצליל, כמו יצירת פודקאסטים או ספרי אודיו.

במדריך הזה מוסבר איך ליצור אודיו מטקסט עם דובר אחד או כמה דוברים באמצעות Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) ו-Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts).

לפני שמתחילים

חשוב לוודא שאתם משתמשים במודל Gemini TTS שמופיע בקטע מודלים נתמכים, ולשדרג לגרסה האחרונה של Google GenAI SDK‏ (google-genai >= 2.25.0 ל-Python או @google/genai >= 2.24.0 ל-JavaScript/TypeScript) או להשתמש ב-API בארכיטקטורת REST. כדי לקבל את התוצאות הטובות ביותר, כדאי לעיין במאמר מתי כדאי להשתמש בכל מודל כדי לבחור את המודל שהכי מתאים לעומס העבודה שלכם.

מומלץ לבדוק את מודלי ה-TTS של Gemini ב-AI Studio לפני שמתחילים לפתח.

המרת טקסט לדיבור (TTS) עם דובר יחיד

כדי להמיר טקסט לאודיו של דובר יחיד באמצעות מודלים של Gemini 3.8 TTS, מעבירים את התמליל המדויק ב-input, מוסיפים סגנון ברמת התור באמצעות הערה מסוג speech_metadata ומגדירים את הקול ב-generation_config.speech_config. אתם יכולים לבחור קול מתוך אפשרויות הקול המובנות, ספריית הקולות המורחבת (GET /v1beta/voices), מזהה Custom Voice (voice_...) או מזהה רפליקציה של קולות (voice_..., או voicekey_... אופציונלי בלי שמירת מצב).

בדוגמה הזו, פלט האודיו בפורמט WAV שמוגדר כברירת מחדל (audio/wav) נשמר מהמודל ישירות בקובץ:

Python

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

JavaScript

import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
   });

   const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
   fs.writeFileSync('out.wav', audioBuffer);
}
await main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }' | jq -r '[.steps[] | select(.type=="model_output") | .content[] | select(.type=="audio")] | last | .data' | base64 --decode > out.wav

ב-Python SDK וב-JavaScript SDK, אפשר לאחזר נתוני אודיו שנוצרו באמצעות המאפיין הנוח interaction.output_audio, שמחזיר את בלוק האודיו האחרון שנוצר (בתגובות REST JSON גולמיות, האודיו בקידוד base64 מאוחסן ב-steps[].content[].data). פרטים נוספים על מאפיינים נוחים זמינים בסקירה הכללית על אינטראקציות.

המרת טקסט לדיבור (TTS) עם מספר דוברים

בדיאלוג עם כמה דוברים, מגדירים שני דוברים ב-speech_config.speakers ומעבירים כל תור כפריט טקסט נפרד עם הערה speech_metadata שמציינת את speaker ואת style האופציונלי ברמת התור. שימו לב ש-speech_config מקבל מערך ([{"voice": "..."}]) ליצירת קול של דובר יחיד ואובייקט ({"speakers": [...]}) ליצירת קול של כמה דוברים:

Python

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [
            {
                "type": "text",
                "text": "How's it going today Jane?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Joe",
                    "style": "cheerful and friendly",
                }],
            },
            {
                "type": "text",
                "text": "Not too bad, how about you? Ready to test these new voices?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Jane",
                    "style": "calm and relaxed",
                }],
            },
        ],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": {
            "speakers": [
                {"speaker": "Joe", "voice": "Puck"},
                {"speaker": "Jane", "voice": "Kore"},
            ],
        }
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

JavaScript

import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [
            {
               type: 'text',
               text: "How's it going today Jane?",
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Joe',
                  style: 'cheerful and friendly',
               }],
            },
            {
               type: 'text',
               text: 'Not too bad, how about you? Ready to test these new voices?',
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Jane',
                  style: 'calm and relaxed',
               }],
            },
         ],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: {
            speakers: [
               { speaker: 'Joe', voice: 'Puck' },
               { speaker: 'Jane', voice: 'Kore' },
            ],
         },
      },
   });

   const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
   fs.writeFileSync('out.wav', audioBuffer);
}

await main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "How'\''s it going today Jane?",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Joe",
            "style": "cheerful and friendly"
          }]
        },
        {
          "type": "text",
          "text": "Not too bad, how about you? Ready to test these new voices?",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Jane",
            "style": "calm and relaxed"
          }]
        }
      ]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": {
        "mode": "conversational",
        "speakers": [
          { "speaker": "Joe", "voice": "Puck" },
          { "speaker": "Jane", "voice": "Kore" }
        ]
      }
    }
  }'

שליטה בסגנון הדיבור באמצעות מטא-נתונים ותגים

‫Gemini 3.8 TTS מתייחס לשדה text כתמליל מילה במילה. כדי לשלוט באופן ההקראה בלי שהוראות הבימוי יוקראו בקול, פצלו את ההוראות לפי היקף:

  • הגייה רציפה ברמת התור (speech_metadata.style): כדי להוסיף רגשות, סגנון הגייה, פרוזודיה, קצב ועוצמת קול שרלוונטיים לכל התור, צריך להזין אותם בשדה style (לדוגמה, "style": "whispered urgently", "style": "out of breath" או "style": "warm and enthusiastic").
  • אירועים נקודתיים (תגים מוטבעים): הציבו הפסקות או התפרצויות קוליות רגעיות שאינן דיבור ישירות בתוך התמליל באמצעות סוגריים זוויתיים (לדוגמה, "Wait... <short pause> did you hear that? <sigh>" או "Excuse me <cough> as I was saying...").

במדריך לכתיבת הנחיות מפורטות שיטות מומלצות.

Python

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [
            {
                "type": "text",
                "text": "Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Dr. Anya",
                    "style": "whispered urgently",
                }],
            },
            {
                "type": "text",
                "text": "<gasp> No way! <laugh> We've been searching for this species all season!",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Liam",
                    "style": "warm and enthusiastic",
                }],
            },
        ],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": {
            "speakers": [
                {"speaker": "Dr. Anya", "voice": "Kore"},
                {"speaker": "Liam", "voice": "Puck"},
            ],
        }
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

JavaScript

import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [
            {
               type: 'text',
               text: 'Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?',
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Dr. Anya',
                  style: 'whispered urgently',
               }],
            },
            {
               type: 'text',
               text: "<gasp> No way! <laugh> We've been searching for this species all season!",
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Liam',
                  style: 'warm and enthusiastic',
               }],
            },
         ],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: {
            speakers: [
               { speaker: 'Dr. Anya', voice: 'Kore' },
               { speaker: 'Liam', voice: 'Puck' },
            ],
         },
      },
   });

   if (interaction.output_audio?.data) {
      const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
      fs.writeFileSync('out.wav', audioBuffer);
   }
}

await main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Dr. Anya",
            "style": "whispered urgently"
          }]
        },
        {
          "type": "text",
          "text": "<gasp> No way! <laugh> We'\''ve been searching for this species all season!",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Liam",
            "style": "warm and enthusiastic"
          }]
        }
      ]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": {
        "speakers": [
          { "speaker": "Dr. Anya", "voice": "Kore" },
          { "speaker": "Liam", "voice": "Puck" }
        ]
      }
    }
  }'

יצירת דיבור בסטרימינג

כדי להעביר בסטרימינג את האודיו שנוצר בזמן שהוא מסונתז, מגדירים את stream: true. בשונה מבקשות unary (שמחזירות קובץ WAV מלא עם כותרת RIFF), בקשות סטרימינג מחזירות נתחי PCM לינאריים של 16 ביט חתומים בפורמט little-endian (audio/l16,‏ 24 kHz,‏ מונו) ללא כותרת כברירת מחדל, כך שאפשר להפעיל או לחבר ברצף נתחי אודיו ללא כותרות של קונטיינר.

Python

import base64
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
    stream=True,
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "audio":
            audio_data = base64.b64decode(event.delta.data)
            # Process the audio chunk (e.g. play it or write to a file)

JavaScript

import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const stream = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
      stream: true,
   });

   for await (const event of stream) {
      if (event.event_type === 'step.delta') {
         if (event.delta.type === 'audio') {
            const audioBuffer = Buffer.from(event.delta.data, 'base64');
            // Process the audio buffer
         }
      }
   }
}
await main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    },
    "stream": true
  }'

פורמטים של פלט אודיו

המודלים של Gemini 3.8 TTS משתמשים בפורמטים שונים של אודיו כברירת מחדל, בהתאם לסוג הבקשה – Unary או סטרימינג:

  • בקשות אונריות (stream=False): מחזירות אודיו מלא בפורמט WAV ‏ (audio/wav) עם כותרת RIFF רגילה (24‎ kHz, מונו, 16 ביט חתום, little-endian PCM). אתם יכולים לשמור את בייטים של האודיו המפוענח ישירות בקובץ .wav בלי להוסיף ידנית כותרת של WAV.
  • בקשות סטרימינג (stream=True): כברירת מחדל, מחזירות מקטעי PCM לינארי גולמי ללא כותרת (audio/l16) (‏24kHz, מונו, PCM מסוג little-endian חתום של 16 ביט), כדי שיהיה אפשר להעביר בסטרימינג או לשרשר מקטעים באופן רציף בלי כותרות של מאגרים בכל מקטע.

כדי לבקש קידוד אודיו או תדירות דגימה אחרים, מגדירים את mime_type ואת sample_rate האופציונלי בתוך response_format:

פורמט ערך של mime_type תיאור
WAV (ברירת המחדל של unary) "audio/wav" קובץ WAV לא דחוס עם כותרת RIFF (‏PCM מסוג little-endian חתום של 16 ביט, מונו, ברירת מחדל של 24kHz). ברירת המחדל לבקשות אונריות.
Raw PCM (L16)‎ (ברירת המחדל לסטרימינג) "audio/l16" אודיו PCM ליניארי לא דחוס, ללא כותרת, 16 ביט, חתום, little-endian ‏ (24 kHz, מונו). ברירת המחדל לבקשות סטרימינג.
Mu-law "audio/mulaw" אודיו בקידוד G.711 mu-law של 8 ביט (נפוץ במערכות טלפוניה/IVR בצפון אמריקה וביפן).
A-law "audio/alaw" אודיו בקידוד G.711 A-law של 8 ביט (נפוץ במערכות טלפוניה אירופאיות ובינלאומיות).

אפשר גם לציין את הערך של sample_rate בהרץ (לדוגמה, 24000,‏ 16000 או 8000).

Python

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={
        "type": "audio",
        "mime_type": "audio/l16",  # "audio/wav" (default), "audio/l16", "audio/mulaw", or "audio/alaw"
        "sample_rate": 24000,
    },
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
)

with open("out.pcm", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

JavaScript

import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: {
         type: 'audio',
         mime_type: 'audio/l16', // 'audio/wav' (default), 'audio/l16', 'audio/mulaw', or 'audio/alaw'
         sample_rate: 24000,
      },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
   });

   const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
   fs.writeFileSync('out.pcm', audioBuffer);
}
await main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio",
      "mime_type": "audio/l16",
      "sample_rate": 24000
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'

אפשרויות קוליות

‫Gemini 3.8 TTS תומך בארבע דרכים לבחירה או ליצירה של קולות:

  1. קולות אולפן מוכנים מראש: 30 קולות שנבחרו בקפידה ומפורטים בטבלה הבאה.
  2. ספריית קולות מורחבת: מאות קולות נוספים בשפות, במבטאים ובארכיטיפים שונים של דמויות, שאפשר לגשת אליהם באמצעות client.voices.list() (GET /v1beta/voices).
  3. עיצוב קול: אתם יכולים ליצור פרסונה קולית בהתאמה אישית מתיאור בשפה טבעית ב-Google AI Studio או באמצעות POST /v1beta/voices (type="prompted", שמחזיר מזהה voice_... קבוע ותצוגה מקדימה של קובץ WAV בנפח sample_audio ב-CreateVoice וב-GetVoice).
  4. ‫שכפול קול: שכפול קול של דובר מאודיו לדוגמה ומהסכמה ב-Google AI Studio או באמצעות POST /v1beta/voices (type="replicated", ‏store=True קבוע כברירת מחדל או store=False אופציונלי ללא שמירת מצב).

מגבלות ו-TTL של קול מותאם אישית

הכתבה מצב אחסון מכסה / מגבלה שמירה (TTL)
קולות עם מצב (voice_..., מונחים או משוכפלים) store=True 200 קולות לכל פרויקט (משותפים בין קולות שנוצרו באמצעות הנחיה וקולות ששוכפלו) שנה ממועד השימוש האחרון*
מפתחות קוליים בלי שמירת מצב (voicekey_..., משוכפלים) store=False בניהול הלקוח 7 ימים

* הארכת משך הזמן: חלון השמירה של שנה מתאפס בכל פעם שמשתמשים בקול באופן פעיל (כדי להמיר טקסט לדיבור או כבסיס ליצירת רמיקס). קולות שלא הייתה בהם פעילות במשך שנה נמחקים באופן אוטומטי.

קולות מוכנים מראש

‫Zephyr -- Bright ‫Puck – Upbeat Charon – אינפורמטיבי
‫Kore – Firm Fenrir – מתלהב Leda – צעיר
Orus – חברה ‫Aoede – Breezy Callirrhoe – נינוח
אוטונואה -- בהיר ‫Enceladus – Breathy Iapetus – בהיר
Umbriel – נינוח Algieba -- Smooth Despina -- Smooth
Erinome -- Clear ‫Algenib -- מחוספס Rasalgethi – אינפורמטיבי
‫Laomedeia – שמח Achernar – רך Alnilam -- Firm
‫Schedar – Even Gacrux – בוגר Pulcherrima -- תהודה קדמית
Achird – ידידותי Zubenelgenubi -- רגוע ‫Vindemiatrix – עדין
Sadachbia – Lively Sadaltager – בעל ידע Sulafat -- חמה

ספריית קולות מורחבת וסינון

בנוסף ל-30 הקולות המוצגים בטבלה שלמעלה, ספריית הקולות המורחבת כוללת מאות קולות נוספים בשפות שונות, עם מבטאים אזוריים, דמויות וסגנונות שונים. אתם יכולים לעיין בספריית הקולות המלאה, לסנן אותה ולשמוע דוגמיות באופן אינטראקטיבי ב-Google AI Studio, או לשלוח שאילתות באופן פרוגרמטי באמצעות client.voices.list() (GET /v1beta/voices, באמצעות google-genai בגרסה 2.25.0 ומעלה או @google/genai בגרסה 2.24.0 ומעלה).

‫ListVoices מחזירה את הקולות המותאמים אישית ששמרתם (בסדר מהחדש לישן), ואחריהם את הקולות המוכנים מראש שמתאימים לקריטריונים של המסנן. כשמעבירים כמה ערכים למסנן רשימה, המערכת מחזירה את הקולות שתואמים לכל ערך במסנן הזה (OR), ואילו פרמטרים נפרדים של מסנן משולבים עם AND:

פרמטר סוג תיאור
language_code list[str] תגי שפה בתקן BCP-47 (לדוגמה, ["en-US", "en-GB"]). התאמה מדויקת לא תלוית-רישיות.
region_code list[str] קודים של אזורים לפי תקן ISO 3166-1 alpha-2 או תקן UN M.49 (לדוגמה, ["US", "GB"]).
accent list[str] תיאור של מבטא אזורי (לדוגמה, ["American", "British"]).
gender list[str] הצגת המגדר הנתפס ("female", "male" או "neutral").
pitch list[str] סיווג גובה הקול ("low",‏ "medium" או "high").
persona list[str] פרסונה קולית או אב טיפוס של דמות (לדוגמה, ["Warm, Friendly"], ["Narrator"]).
‫contexts (context ב-REST) list[str] דומיין לשימוש אופטימלי (לדוגמה, ["Audiobook", "Conversational", "News"]).
‫type (type_ ב-Python) list[str] מסננים לפי מקור הקול: "prebuilt", "prompted" (עיצוב קול) או "replicated" (רפליקציה של קולות).
search str חיפוש מחרוזת משנה של טקסט חופשי התאים ל-display_name ול-description לא תלוי-רישיות.
page_size int המספר המקסימלי של קולות שמוחזרים בכל דף (ברירת המחדל היא 50, המקסימום הוא 1000).
page_token str טוקן מ-response.next_page_token כדי לאחזר את דף התוצאות הבא.

Python

from google import genai

client = genai.Client()

# Filter the Voice Library by language, gender, pitch, domain context, and keyword
response = client.voices.list(
    language_code=["en-US", "en-GB"],
    gender=["female"],
    pitch=["medium", "low"],
    contexts=["Audiobook", "Conversational"],
    type_=["prebuilt"],
    search="warm",
    page_size=50,
)

for voice in response.voices or []:
    print(
        f"{voice.id} | {voice.display_name} ({voice.language_code},"
        f" {voice.accent}, {voice.gender}, pitch={voice.pitch}):"
        f" {voice.description}"
    )

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

// Filter the Voice Library by language, gender, pitch, domain context, and keyword
const response = await ai.voices.list({
  language_code: ["en-US", "en-GB"],
  gender: ["female"],
  pitch: ["medium", "low"],
  contexts: ["Audiobook", "Conversational"],
  type: ["prebuilt"],
  search: "warm",
  page_size: 50,
});

for (const voice of response.voices ?? []) {
  console.log(
    `${voice.id} | ${voice.display_name} (${voice.language_code}, ${voice.accent}, ${voice.gender}, pitch=${voice.pitch}): ${voice.description}`
  );
}

REST

curl -G "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --data-urlencode "language_code=en-US" \
  --data-urlencode "language_code=en-GB" \
  --data-urlencode "gender=female" \
  --data-urlencode "pitch=medium" \
  --data-urlencode "context=Audiobook" \
  --data-urlencode "type=prebuilt" \
  --data-urlencode "search=warm" \
  --data-urlencode "page_size=50"

שפות נתמכות

המודלים של המרת טקסט לדיבור מזהים את שפת הקלט באופן אוטומטי. ‫Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) תומך ביותר מ-130 שפות, ו-Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) תומך ביותר מ-100 שפות:

שפה Gemini 3.8 Flash TTS Gemini 3.8 Flash-Lite TTS
אצ'ה (כתב ערבי) ✔️ ✔️
אפריקאנס ✔️ ✔️
אקאן ✔️ ✔️
אמהרית ✔️ ✔️
ארמנית ✔️ ✔️
אסאמית ✔️ ✔️
עוואדי ✔️ ✔️
באלינזית ✔️ ✔️
בנגלית ✔️ ✔️
בנג'אר (כתב ערבי) ✔️ —
בנג'אר (כתב לטיני) ✔️ ✔️
בשקירית ✔️ —
בסקית ✔️ ✔️
בלארוסית ✔️ ✔️
במבה ✔️ —
בוג'פורי ✔️ ✔️
בוסנית ✔️ ✔️
בוגינזית ✔️ ✔️
בולגרית ✔️ ✔️
בורמזית ✔️ —
קנטונזית ✔️ ✔️
קטלאנית ✔️ ✔️
סבואנו ✔️ ✔️
כורדית מרכזית ✔️ ✔️
צ'אטיסגארי ✔️ ✔️
סינית (כתב האן פשוט) ✔️ ✔️
סינית (כתב האן) ✔️ ✔️
טטארית של חצי האי קרים ✔️ —
קרואטית ✔️ ✔️
צ'כית ✔️ ✔️
דנית ✔️ ✔️
הולנדית ✔️ ✔️
דיולה ✔️ —
דזונקה ✔️ —
ערבית מצרית ✔️ ✔️
אנגלית ✔️ ✔️
אסטונית ✔️ ✔️
פיליפינית ✔️ ✔️
פינית ✔️ —
צרפתית ✔️ ✔️
גליציאנית ✔️ ✔️
גאנדה ✔️ ✔️
גאורגית ✔️ ✔️
גרמנית ✔️ ✔️
יוונית ✔️ ✔️
גוארני ✔️ —
גוג'ראטי ✔️ ✔️
קריאולית האיטית ✔️ ✔️
מונגולית חלחה ✔️ ✔️
האוסה ✔️ ✔️
עברית ✔️ ✔️
הינדי ✔️ ✔️
הונגרית ✔️ ✔️
איסלנדית ✔️ ✔️
איגבו ✔️ —
אילוקו ✔️ ✔️
אינדונזית ✔️ ✔️
פרסית איראנית ✔️ ✔️
איטלקית ✔️ ✔️
יפנית ✔️ ✔️
ג'אווה ✔️ ✔️
קביל ✔️ —
קאמבה ✔️ ✔️
קנאדה ✔️ ✔️
קשמירית (כתב ערבי) ✔️ ✔️
קשמירית (כתב דוונאגרי) ✔️ ✔️
קזחית ✔️ ✔️
חמרית ✔️ ✔️
קיקויו ✔️ ✔️
קינירואנדה ✔️ ✔️
קונגו ✔️ ✔️
קוריאנית ✔️ ✔️
קירגיזית ✔️ ✔️
לאו ✔️ ✔️
לטגאלית ✔️ —
לינגלה ✔️ ✔️
ליטאית ✔️ —
לוקסמבורגית ✔️ —
מקדונית ✔️ ✔️
מגאהי ✔️ ✔️
מאיטילית ✔️ ✔️
מליאלאם ✔️ ✔️
מלטית ✔️ ✔️
מניפורית ✔️ ✔️
מראטהית ✔️ ✔️
מיננגקבאו (כתב ערבי) ✔️ ✔️
מיננגקבאו (אותיות לטיניות) ✔️ —
מיזו ✔️ ✔️
נפאלית (שפה נפרדת) ✔️ ✔️
פולפולדה ניגרית ✔️ ✔️
אזרית צפונית ✔️ ✔️
סוטו צפונית ✔️ ✔️
צפון אוזבקי ✔️ ✔️
‏נורבגית ספרותית ✔️ ✔️
נורווגית (Nynorsk) ✔️ ✔️
ניאנג'ה ✔️ ✔️
אוקסיטנית ✔️ —
אודייה (שפה נפרדת) ✔️ ✔️
פנגסינאן ✔️ —
פרסית (אפגניסטן) ✔️ ✔️
פולנית ✔️ ✔️
פורטוגזית ✔️ ✔️
פנג'אבי ✔️ ✔️
רומנית ✔️ ✔️
רוסית ✔️ ✔️
סנטלי ✔️ ✔️
סרבית ✔️ ✔️
סינדהית ✔️ —
סינהאלה ✔️ ✔️
סלובקית ✔️ ✔️
סלובנית ✔️ —
סומלית ✔️ —
אזרית דרומית ✔️ ✔️
פאשטו דרומית ✔️ ✔️
סוטו דרומית ✔️ —
ספרדית ✔️ ✔️
ערבית סטנדרטית (כתב ערבי) ✔️ ✔️
ערבית תקנית (כתב לטיני) ✔️ ✔️
לטבית רגילה ✔️ ✔️
מלאית תקנית ✔️ ✔️
סוואהילי (שפה נפרדת) ✔️ —
סוואטי ✔️ —
שוודית ✔️ —
טג'יקית ✔️ —
טמילית ✔️ ✔️
טלוגו ✔️ ✔️
תאית ✔️ —
תיגרינית ✔️ —
אלבנית טוסק ✔️ —
טורקית ✔️ ✔️
אויגור ✔️ —
וייטנאמית ✔️ ✔️

מודלים נתמכים

מודל דובר יחיד מערכת רמקולים עיצוב קול רפליקציה של קולות
‫Gemini 3.8 Flash TTS‏ (gemini-3.8-flash-tts) ✔️ ✔️ ✔️ ✔️
‫Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) ✔️ ✔️ ✔️ ✔️
Gemini 3.1 Flash TTS Preview ✔️ ✔️ — —
Gemini 2.5 Pro Preview TTS ✔️ ✔️ — —

מתי להשתמש בכל מודל

שני מודלי ה-TTS של Gemini 3.8 חולקים את אותה סכימת API ואת אותו פורמט הנחיות, כך שאפשר לעבור ביניהם באמצעות שינוי של פרמטר אחד:

  • השתמשו ב-Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) כשאתם צריכים דיוק אקוסטי מקסימלי, משחק ניואנסי ושליטה בהבעה. הוא מתאים במיוחד לעבודות יצירתיות ברמה של אולפן, לדיאלוגים מורכבים עם כמה דוברים, לתגי קול חזקים, להגייה מסובכת, לניבים אזוריים או של מיעוטים ולקריינות ארוכות שדורשות יציבות מושלמת של הקול ושל טון החדר.
  • השתמשו ב-Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) כמודל מהיר וחסכוני שיחליף את gemini-3.1-flash-tts-preview. הוא מותאם להפקה בכמות גדולה, לשיחות עם נציגים קוליים, לתכונות של קריאה בקול רם, לרפליקציה של קולות מהימנה ולדיבור יומיומי בשפה אחת בשפות מרכזיות.

מדריך להעברת נתונים (מיגרציה)

אם אתם מבצעים מיגרציה מגרסה gemini-3.1-flash-tts-preview או מגרסאות קודמות של מודלים של Gemini TTS אל Gemini 3.8 TTS:

  1. העברת הוראות ברמת הפנייה ל-speech_metadata: Gemini 3.8 TTS מתייחס לטקסט הקלט כאל תמליל מילולי בלבד. העברת הוראות בימוי (style—כמו "whispering", "out of breath" או "speaking slowly") ותוויות לזיהוי דוברים (speaker) להערות מובנות speech_metadata במקום להטמיע הוראות בימוי בטקסט של התמליל.
  2. השתמשו בתגים מוטבעים בסוגריים זוויתיים רק לאירועים קוליים בנקודת זמן מסוימת: השאירו קולות רגעיים שאינם דיבור והפסקות מוטבעים בתמליל באמצעות סוגריים זוויתיים (כמו <laugh>, <sigh>, <cough>, <breath> או <short pause>). הימנעו מתגי אפקטים קוליים (כמו מחיאות כפיים או חבטות) והוסיפו סגנונות דיבור ב-speech_metadata.style.
  3. ציינו את speaker בכל תור בבקשות עם כמה דוברים: כל תור בבקשה עם כמה דוברים חייב לכלול באופן מפורש את speaker בתוך speech_metadata, שתואם לאחד מהדוברים שהוגדרו.
  4. הגדרת פרסונות מראש באמצעות Voice design: מחליפים בלוקים של "Audio Profile" או "Director's Notes" עם כמה פסקאות בקול בהתאמה אישית שנוצר ב-Voice design, ואז מעבירים את המזהה של voice_... בבקשות ה-TTS עם מחרוזות style מינימליות או ריקות.
  5. הסבר על פלט WAV (audio/wav) כברירת מחדל בבקשות unary: בניגוד למודלים של TTS מגרסה gemini-3.1-flash-tts-preview ומגרסאות קודמות (שבהם הוחזר PCM גולמי ללא כותרת audio/l16 כברירת מחדל), מודל Gemini 3.8 TTS מחזיר אודיו בפורמט WAV (audio/wav) עם כותרת RIFF רגילה כברירת מחדל לבקשות unary.
    • אם הקוד שלכם עטף בעבר בייטים של PCM גולמי בכותרת WAV (לדוגמה, באמצעות המודול wave של Python או ffmpeg), הסירו את מעטפת הכותרת הידנית וכתבו את הבייטים שהוחזרו ישירות לקובץ .wav.
    • אם צינור עיבוד הנתונים דורש אודיו בפורמט PCM,‏ mu-law או A-law ללא כותרת, צריך להגדיר במפורש את response_format.mime_type לערך "audio/l16",‏ "audio/mulaw" או "audio/alaw" (לדוגמה, {"response_format": {"type": "audio", "mime_type": "audio/l16"}} ב-Interactions API או AUDIO_L16 ב-generateContent). מידע נוסף זמין בקטע פורמטים של פלט אודיו.

מדריך לכתיבת פרומפטים

מודלים של Gemini 3.8 TTS מתייחסים לטקסט הקלט כאל תמליל מילה במילה. בניגוד למודלים קודמים של גרסאות טרום-השקה, שבהם הוראות הבימוי היו מוטמעות בטקסט פשוט, ב-Gemini 3.8 TTS יש הפרדה בין הוראות מתמשכות ברמת התור (speech_metadata) לבין תגי קול מוטמעים בנקודת זמן ספציפית.

שדה סגנון לעומת תגים בתוך השורה

הוראות הביצוע מחולקות לפי היקף:

  • העברה ברמת הפנייה (speech_metadata.style): מכניסים מאפייני העברה מתמשכת – כמו רגש, פרוזודיה, קצב כללי או סגנון העברה (למשל "whispering", "out of breath", "muttering" או "sarcastic") – לשדה style של speech_metadata. כדי ליצור דמות וביצועים יציבים לאורך כל התורות, כדאי לעצב את הדמות מראש בעיצוב הקול ולהשתמש ב-style רק לשינויים אופציונליים ברמת התור.
  • אירועים בנקודת זמן מסוימת (תגים מוטבעים): כדי להוסיף לטקסט תמלול פרצי קול רגעיים שאינם דיבור, נשימות או הפסקות, משתמשים בסוגריים זוויתיים (<cough>, <breath>, <sigh>, <short pause>). כדי לקבל את איכות האודיו הכי גבוהה, משתמשים בסוגריים זוויתיים (<...>) ומוסיפים רק קולות אנושיים ולא אפקטים קוליים שאינם קולות.
היקף איפה למקם את המכשיר דוגמאות
ברמת התור (נמשך לאורך התור) speech_metadata.style "angry tone",‏ "speaking rapidly",‏ "out of breath",‏ "whispers",‏ "sarcastic"
בנקודת זמן (מתרחש במילה ספציפית) בתוך השורה ב-text (<...>) "<cough> Thank you all for coming tonight! <throat-clearing> As I was saying..."

קצב והפסקות

אתם יכולים לשלוט בקצב ובשתיקה בשלוש רמות פירוט:

  • סימני פיסוק ושלוש נקודות: השתמשו בפסיקים, במקפים (--) ובשלוש נקודות (...) כדי ליצור היסוס טבעי בשיחה.
  • תגי השהיה בתוך השורה: מוסיפים את התגים <short pause> או <long pause> בנקודות המדויקות בסקריפט שבהן הדובר צריך להשהות את הדיבור: text Hold on, let me think... <short pause> Alright, I've got it.
  • קצב ברמת התור: מגדירים את "style": "speaking rapidly" או את "style": "speaking slowly" ב-speech_metadata כדי לשלוט בקצב הדיבור לאורך כל התור.

פרוזודיה וגובה הצליל

משתמשים ב-speech_metadata.style כדי לשלוט בפרוזודיה, בגובה הצליל ובאינטונציה לאורך תור (לדוגמה, "style": "high pitch, cheerful and excited inflection" או "style": "monotone and flat"). אם יש שינוי ברגש או בפרוזודיה באמצע הדיאלוג, צריך לפצל את התסריט לתורות נפרדות עם ערכי style שונים לכל תור.

הדגשה

כדי להדגיש מילים מרכזיות בדיבור באופן טבעי, אפשר להשתמש באותיות רישיות למילים ספציפיות בתמליל, בשילוב עם סימני פיסוק ותגי דיבור מוטבעים:

This is a VERY important point!
It was a VERY long day <sigh> ... nobody listens anymore.

התפרצויות קוליות וצלילים שאינם דיבור

כדי להוסיף קולות אנושיים שאינם דיבור, צריך להשתמש בסוגריים זוויתיים (<...>) בנקודה המדויקת שבה הצליל אמור להופיע. תגי הקול המומלצים כוללים:

<argh> <breath> <heavy breath> <exhales>
<cackle> <cheer> <chuckle> / <chuckles> <cough>
<cry> <gasp> <giggle> <groan>
<growl> <grunt> <grr> <hiss>
<laugh> / <laughter> <moan> <pant> <pff> / <phew>
<scream> <shout> <shriek> <sigh> / <sighs>
<sneeze> <snicker> <snort> <sob>
<throat-clearing> <tsk> <whimper> <whispers> / <whispering>
<yawn> <short pause> <long pause>

ערוצים אחוריים ודיבור חופף

בדיאלוג עם כמה דוברים, כדי ליצור ערוצים משניים טבעיים או דיבור חופף בלי ליצור תור נפרד לכל תגובה, צריך להוסיף את התגובות של המאזינים בתוך תור הדיבור של הדובר, בין שני קווים אנכיים (|reaction|).

  • תגובות קצרות של המאזין: תגובות קצרות של המאזין (|oh hmm|, |oh really?|, |absolutely|) במהלך הדיבור של הדובר הפעיל:
    • תור 1 (דובר א'): "So the launch is Thursday |oh hmm| Are we actually ready?"
    • תור 2 (דובר ב'): "Ready enough |oh really?| The last blocker cleared this morning."
    • תור 3 (דובר א'): "Then let's ship it |absolutely| and watch the dashboards."
  • דיבור חופף ומשולב: כדי לדמות דיבור בו-זמני או משולב בין שני דוברים, משתמשים בכמה מקטעים עם קו אנכי (האפשרות הזו מתאימה במיוחד ל-gemini-3.8-flash-tts):
    • ספירה לאחור/פזמון בו-זמנית: "Let's surprise him on three |ok| ready?" ואחריו "one. two. three. |happy| happy |birthday| birthday!"
    • חפיפה מלאה בין הדוברים: "Hello |oh| there |my| it |goodness| must |gracious| be |would| almost |you| time |look| for |at that| dinner"

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

כדי לשמור על זהות קולית יציבה לאורך כל התורות, חשוב לפעול לפי ההנחיות הבאות:

  • עיצוב פרסונות מראש בעיצוב קולי במקום בלוקים ארוכים של סגנון: פסקאות ארוכות "Audio Profile" ורשימות עם כמה תתי-נקודות "Director's Notes" שהועברו ממודלים קודמים הן הסיבה הנפוצה ביותר לשינוי קולי. אתם יכולים להשתמש באותה אינטואיציה יצירתית מראש בעיצוב הקול כדי ליצור דמות מותאמת אישית קבועה של voice_..., ואז להעביר את מזהה הקול הזה דרך הקריאות ל-TTS.
  • הסתמכות על הפניה קולית ליציבות (השמטת הוראות מטא): המודלים של Gemini 3.8 TTS מאומנים להתמקד קודם בהפניה לאודיו. אל תכללו הוראות שאומרות למודל לשמור על קול יציב (כמו "do not switch speaker identity" או "maintain identical timbre") – טקסט נוסף בהנחיה מגביר את הסטייה. מומלץ להשמיט הוראות סגנון מיותרות ולאפשר למודל להשתנות באופן טבעי סביב נקודת היציבות שסופקה על ידי רפרנס הקול.
  • אל תנסו לשנות מאפיינים קבועים של הדובר ב-style: אל תציינו גיל, מגדר, שמות או שינויים קבועים במבטא ב-speech_metadata.style. במקום זאת, אפשר לבחור קול אזורי מתוך ספריית הקולות המורחבת או ליצור קול באמצעות עיצוב קול.
  1. יוצרים את הדמות פעם אחת: יוצרים את הדמות ב-Voice design או בוחרים קול אזורי מספריית הקולות המורחבת שמתאים לשפת היעד ולפרסונה.
  2. כתיבת תמלילים של דיבור טבעי עם שיבושי דיבור: כדי להשיג את התוצאה הטבעית ביותר, כדאי לכתוב את text כתמליל של דיבור אמיתי – כולל שיבושי דיבור והיסוסים טבעיים (לדוגמה, "Oh uh yeah I think... hm, so that's interesting").
  3. קודם בודקים TTS רגיל: מסנתזים את התמליל עם שדה style ריק – ברוב הבקשות לא צריך לתת הוראות style בכלל.
  4. הוסיפו הנחיות קצרות של style רק לשינויים קלים: הוסיפו מחרוזת style תמציתית (כמו "casual, friendly" או "muttering, then reassuring") רק לחלקים שצריך לשנות בהם את אופן ההגשה, והשתמשו שוב באותה מחרוזת קצרה בחלקים שונים כשאתם רוצים לשמור על קו בסיס עקבי.

סוכני שיחה וסוכנים קוליים רב-שלביים

כשמפתחים סוכנים קוליים לשיחות בזמן אמת או אפליקציות עם כמה שלבים:

  • מבצעים קריאת TTS אחת בכל תור כשמגיעים קטעי טקסט של LLM.
  • מאפשרים ל-voice שהוגדר (מוכן מראש, מעוצב voice_... או משוכפל voice_... / voicekey_...) לשמור את הזהות של הדובר לאורך כל התורות – לא לשלוח מחדש דמות ארוכה בכל תור.
  • השאירו את השדה style של כל פנייה ריק, או שלחו מחרוזת קבועה קצרה אחת (כמו "casual, friendly") לכל השיחה.
  • פצלו תשובות ארוכות של הנציג לחלקים קצרים יותר, במקום להשתמש בהנחיות סגנון חזקות יותר.

מגבלות

  • מודלים של TTS מקבלים קלט של טקסט בלבד ומפיקים פלט של אודיו בלבד.
  • יצירה של כמה דוברים בבקשה אחת (speech_config.speakers) תומכת בעד 2 דוברים באמצעות קולות מוכנים מראש. כדי לשלב קולות מותאמים אישית (voice_...) או קולות משוכפלים (voice_... / voicekey_...) בדיאלוג של כמה דמויות, צריך לבצע סינתזה של כל תור דיבור בנפרד. כברירת מחדל, בקשות Unary מחזירות audio/wav עם כותרת RIFF של 44 בייטים. לכן, צריך לבקש PCM גולמי ({"type": "audio", "mime_type": "audio/l16"}) או להסיר את כותרת ה-WAV מכל תור לפני שמשרשרים את הפריימים של האודיו ב-PCM של 24kHz.
  • מכסות אחסון וערכי TTL מותאמים אישית לקולות:
    • קולות עם שמירת מצב (store=True, בהנחיה או בשכפול): עד 200 קולות לכל פרויקט עם אורך חיים של שנה (TTL).
    • מפתחות קול ללא שמירת מצב (store=False, voicekey_...): אורך חיים (TTL) של 7 ימים.
  • בקטע שפות נתמכות מפורטות השפות שבהן אפשר להשתמש.

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