تولید متن به گفتار (TTS)

API Gemini می‌تواند ورودی متن را با استفاده از قابلیت‌های تولید متن به گفتار (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 که در بخش مدل‌های پشتیبانی‌شده ذکر شده است، استفاده می‌کنید. برای نتایج بهینه، بررسی کنید که چه زمانی از کدام مدل استفاده کنید تا بهترین مدل را برای حجم کاری خود انتخاب کنید.

ممکن است قبل از شروع ساخت، آزمایش مدل‌های Gemini TTS در AI Studio مفید باشد.

TTS تک بلندگو

برای تبدیل متن به صدای تک‌گوینده با مدل‌های TTS در Gemini 3.8، متن رونوشت کلمه به کلمه را در parts[].text کنید، استایل نوبت‌دهی را در parts[].speech_metadata پیوست کنید و صدای خود را در speechConfig.voiceConfig پیکربندی کنید. می‌توانید یک نام صدای از پیش ساخته شده، یک شناسه کتابخانه صدای توسعه یافته، یک شناسه طراحی صدای سفارشی ( voice_... ) یا یک شناسه تکثیر صدا ( voice_... ) یا یک voicekey_... بدون وضعیت اختیاری را ارسال کنید.

این مثال صدای خروجی از مدل را در یک فایل WAV ذخیره می‌کند:

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {"style": "cheerful and friendly"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "voice_config": {"voice": "Kore"}
        },
    },
)

data = response.candidates[0].content.parts[0].inline_data.data
with open("out.wav", "wb") as f:
    f.write(data)

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

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

   const response = await ai.models.generateContent({
      model: 'gemini-3.8-flash-tts',
      contents: [{
         role: 'user',
         parts: [{
            text: 'Have a wonderful day!',
            speechMetadata: { style: 'cheerful and friendly' },
         }],
      }],
      config: {
         responseModalities: ['AUDIO'],
         speechConfig: {
            voiceConfig: { voice: 'Kore' },
         },
      },
   });

   const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
   const audioBuffer = Buffer.from(data, 'base64');

   fs.writeFileSync('out.wav', audioBuffer);
}
await main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-tts:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "contents": [{
          "role": "user",
          "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {
              "style": "cheerful and friendly"
            }
          }]
        }],
        "generationConfig": {
          "responseModalities": ["AUDIO"],
          "speechConfig": {
            "voiceConfig": {
              "voice": "Kore"
            }
          }
        }
    }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | \
          base64 --decode > out.wav

TTS چند بلندگو

برای گفتگوی چند گوینده، دو گوینده را در multiSpeakerVoiceConfig.speakerVoiceConfigs با استفاده از prebuiltVoiceConfig پیکربندی کنید و هر نوبت گفتگو را به عنوان یک part جداگانه با speech_metadata که هم speaker و هم style سطح نوبت اختیاری را مشخص می‌کند، ارسال کنید:

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [
            {
                "text": "How's it going today Jane?",
                "speech_metadata": {
                    "speaker": "Joe",
                    "style": "cheerful and friendly",
                },
            },
            {
                "text": "Not too bad, how about you? Ready to test these new voices?",
                "speech_metadata": {
                    "speaker": "Jane",
                    "style": "calm and relaxed",
                },
            },
        ],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "multi_speaker_voice_config": {
                "speaker_voice_configs": [
                    {
                        "speaker": "Joe",
                        "voice_config": {
                            "prebuilt_voice_config": {"voice_name": "Puck"}
                        },
                    },
                    {
                        "speaker": "Jane",
                        "voice_config": {
                            "prebuilt_voice_config": {"voice_name": "Kore"}
                        },
                    },
                ]
            }
        },
    },
)

data = response.candidates[0].content.parts[0].inline_data.data
with open("out.wav", "wb") as f:
    f.write(data)

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

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

   const response = await ai.models.generateContent({
      model: 'gemini-3.8-flash-tts',
      contents: [{
         role: 'user',
         parts: [
            {
               text: "How's it going today Jane?",
               speechMetadata: {
                  speaker: 'Joe',
                  style: 'cheerful and friendly',
               },
            },
            {
               text: 'Not too bad, how about you? Ready to test these new voices?',
               speechMetadata: {
                  speaker: 'Jane',
                  style: 'calm and relaxed',
               },
            },
         ],
      }],
      config: {
         responseModalities: ['AUDIO'],
         speechConfig: {
            multiSpeakerVoiceConfig: {
               speakerVoiceConfigs: [
                  {
                     speaker: 'Joe',
                     voiceConfig: {
                        prebuiltVoiceConfig: { voiceName: 'Puck' },
                     },
                  },
                  {
                     speaker: 'Jane',
                     voiceConfig: {
                        prebuiltVoiceConfig: { voiceName: 'Kore' },
                     },
                  },
               ],
            },
         },
      },
   });

   const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
   const audioBuffer = Buffer.from(data, 'base64');

   fs.writeFileSync('out.wav', audioBuffer);
}

await main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-tts:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [
        {
          "text": "How'\''s it going today Jane?",
          "speech_metadata": {
            "speaker": "Joe",
            "style": "cheerful and friendly"
          }
        },
        {
          "text": "Not too bad, how about you? Ready to test these new voices?",
          "speech_metadata": {
            "speaker": "Jane",
            "style": "calm and relaxed"
          }
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "multiSpeakerVoiceConfig": {
          "speakerVoiceConfigs": [
            {
              "speaker": "Joe",
              "voiceConfig": {
                "prebuiltVoiceConfig": { "voiceName": "Puck" }
              }
            },
            {
              "speaker": "Jane",
              "voiceConfig": {
                "prebuiltVoiceConfig": { "voiceName": "Kore" }
              }
            }
          ]
        }
      }
    }
  }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | \
      base64 --decode > out.wav

کنترل سبک گفتار با ابرداده و برچسب‌ها

Gemini 3.8 TTS با فیلد text دقیقاً به عنوان یک متن کلمه به کلمه رفتار می‌کند. برای کنترل تحویل بدون اینکه دستورالعمل‌های صحنه با صدای بلند خوانده شوند، دستورالعمل‌های خود را بر اساس دامنه تقسیم کنید:

• ارائه پایدار در سطح نوبت ( speech_metadata.style ): احساسات، سبک ارائه، نوای کلام، سرعت و بلندی صدایی که در کل یک نوبت اعمال می‌شود را در speech_metadata.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..." ).

برای بهترین شیوه‌های جامع، به راهنمای Prompting مراجعه کنید.

گزینه‌های صوتی

Gemini 3.8 TTS از چهار روش برای انتخاب یا ایجاد صداها پشتیبانی می‌کند:

1. صداهای استودیویی از پیش ساخته شده: 30 صدای منتخب که در جدول زیر فهرست شده‌اند.
2. کتابخانه صوتی توسعه‌یافته: صدها صدای اضافی در زبان‌ها، لهجه‌ها و الگوهای کاراکتر مختلف که با استفاده از client.voices.list() ( GET /v1beta/voices ) قابل دسترسی هستند.
3. طراحی صدا : یک شخصیت صوتی سفارشی از توضیحات زبان طبیعی در Google AI Studio یا با استفاده از POST /v1beta/voices ( type="prompted" که یک شناسه voice_... دائمی و یک پیش‌نمایش sample_audio WAV در CreateVoice و GetVoice برمی‌گرداند) ایجاد کنید.
4. تکرار صدا : صدای گوینده را از صدای مرجع و صدای تایید شده در Google AI Studio یا با استفاده از POST /v1beta/voices ( type="replicated" ، مقدار ثابت store=True به طور پیش‌فرض یا مقدار اختیاری stateless store=False ) کپی کنید.

محدودیت‌های صوتی سفارشی و TTL

* افزونه‌ی TTL: هر بار که صدا به طور فعال استفاده شود (چه با ترکیب گفتار با صدا و چه با استفاده از آن به عنوان صدای پایه برای ریمیکس)، پنجره‌ی نگهداری ۱ ساله بازنشانی می‌شود. صداهایی که به مدت ۱ سال هیچ فعالیتی نداشته باشند، به طور خودکار حذف می‌شوند.

صداهای از پیش ساخته شده

کتابخانه صوتی توسعه‌یافته و فیلترینگ

فراتر از 30 صدای استودیویی برجسته در جدول قبلی، کتابخانه صدای توسعه‌یافته صدها صدای اضافی را در زبان‌ها، لهجه‌های منطقه‌ای، شخصیت‌های شخصیتی و دامنه‌ها ارائه می‌دهد. می‌توانید کل کتابخانه صدا را به صورت تعاملی در Google AI Studio مرور، فیلتر و تست کنید، یا با استفاده از client.voices.list() به صورت برنامه‌نویسی شده از آن پرس‌وجو کنید ( GET /v1beta/voices ، با استفاده از google-genai 2.25.0+ / @google/genai 2.24.0+).

ListVoices صداهای ذخیره شده سفارشی شما (به ترتیب جدیدترین‌ها) و به دنبال آن صداهای کاتالوگ از پیش ساخته شده که با معیارهای فیلتر شما مطابقت دارند را برمی‌گرداند. هنگامی که چندین مقدار برای یک فیلتر لیست ارسال می‌شوند، صداهایی که با هر مقداری در آن فیلتر مطابقت دارند ( OR ) برگردانده می‌شوند، در حالی که پارامترهای فیلتر متمایز با AND ترکیب می‌شوند:

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}"
    )

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}`
  );
}

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"

زبان‌های پشتیبانی‌شده

مدل‌های TTS زبان ورودی را به طور خودکار تشخیص می‌دهند. Gemini 3.8 Flash TTS ( gemini-3.8-flash-tts ) از بیش از ۱۳۰ زبان و Gemini 3.8 Flash-Lite TTS ( gemini-3.8-flash-lite-tts ) از بیش از ۱۰۰ زبان پشتیبانی می‌کنند:

مدل‌های پشتیبانی‌شده

چه زمانی از کدام مدل استفاده کنیم

هر دو مدل Gemini 3.8 TTS دقیقاً طرحواره 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-2.5-pro-preview-tts ) به Gemini 3.8 TTS ( gemini-3.8-flash-tts یا gemini-3.8-flash-lite-tts )، این پنج تغییر کلیدی را بررسی کنید:

1. سبک را از متن پیاده‌شده جدا کنید: دستورالعمل‌های مربوط به بازیگری پیوسته، لحن، عروض و سرعت (مانند "whispering" ، "out of breath" یا "speaking slowly" ) را از متن ساده خارج کرده و به speech_metadata.style منتقل کنید. text دقیقاً به صورت متن پیاده‌شده‌ی کلمه به کلمه به علاوه‌ی برچسب‌های صوتی درون‌خطی نگه دارید.
2. طراحی شخصیت‌ها از قبل با طراحی صدا: بلوک‌های چند پاراگرافی "Audio Profile" یا "Director's Notes" را با یک صدای سفارشی ایجاد شده در طراحی صدا جایگزین کنید، سپس آن شناسه voice_... از طریق درخواست‌های TTS خود با رشته‌های style حداقلی یا خالی منتقل کنید.
3. از نوبت‌های گفتگوی ساختاریافته استفاده کنید: برای گفتگوی چند گوینده، به جای جاسازی پیشوندهای Speaker: ... در یک بلوک متنی، برای هر نوبت گوینده یک part با speech_metadata.speaker ارسال کنید.
4. از براکت‌های زاویه‌دار برای برچسب‌های صوتی درون‌خطی استفاده کنید: برای صداهای انسانی و مکث‌های لحظه‌ای از براکت‌های زاویه‌دار ( <laugh> ، <sigh> ، <cough> ، <breath> ، <short pause> ) استفاده کنید. از برچسب‌های جلوه‌های صوتی غیرکلامی (مانند کف زدن یا ضربه زدن) خودداری کنید.
5. در نظر گرفتن خروجی پیش‌فرض WAV ( AUDIO_WAV ) در درخواست‌های تکی: برخلاف gemini-3.1-flash-tts-preview (که به طور پیش‌فرض PCM خام بدون هدر AUDIO_L16 را برمی‌گرداند)، مدل‌های Gemini 3.8 TTS صدای کامل WAV ( AUDIO_WAV ) را با یک هدر RIFF (24 کیلوهرتز، مونو، PCM 16 بیتی) در درخواست‌های تکی برمی‌گردانند:
   • اگر کد شما قبلاً بایت‌های خام PCM را در یک هدر WAV قرار داده است (برای مثال، با استفاده از ماژول wave پایتون یا بسته wav نود)، پوشش هدر دستی را حذف کرده و بایت‌های صوتی رمزگشایی شده را مستقیماً در یک فایل .wav بنویسید.
   • اگر خط تولید فعلی شما به صدای خام PCM، mu-law یا A-law بدون هدر نیاز دارد، صریحاً response_format.audio.mime_type را روی "AUDIO_L16" ، "AUDIO_MULAW" یا "AUDIO_ALAW" تنظیم کنید (برای مثال، {"response_format": {"audio": {"mime_type": "AUDIO_L16"}}} در generateContent ، یا {"response_format": {"type": "audio", "mime_type": "audio/l16"}} در Interactions API). به بخش فرمت‌های خروجی صدا مراجعه کنید.

راهنمای راهنمایی

مدل‌های 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> ) در متن قرار دهید. برای بالاترین کیفیت صدا از براکت‌های زاویه‌دار ( <...> ) استفاده کنید و به جای جلوه‌های صوتی غیرکلامی، به صداهای انسانی پایبند باشید.

سرعت و مکث

شما می‌توانید ریتم و سکوت را در سه سطح جزئیات کنترل کنید:

• علائم نگارشی و حذف: برای مکث طبیعی در مکالمه از ویرگول، خط تیره ( -- ) و حذف ( ... ) استفاده کنید.
• تگ‌های مکث درون‌خطی: <short pause> یا <long pause> را دقیقاً در نقاطی از فیلمنامه که گوینده باید مکث کند، قرار دهید: text Hold on, let me think... <short pause> Alright, I've got it.
• سرعت نوبت: برای کنترل سرعت صحبت در کل نوبت، در speech_metadata گزینه "style": "speaking rapidly" یا "style": "speaking slowly" را تنظیم کنید.

عروض و آهنگ صدا

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.

انفجارهای صوتی و صداهای غیرگفتاری

صداهای غیرگفتاری انسان را با استفاده از براکت‌های زاویه‌دار ( <...> ) دقیقاً در نقطه‌ای که صدا باید رخ دهد، درون‌خطی قرار دهید. برچسب‌های صوتی توصیه‌شده عبارتند از:

کانال‌های پشتی و گفتار همپوشانی

در گفتگوی چند گوینده، واکنش‌های شنونده را در کاراکترهای پایپ ( |reaction| ) درون نوبت گوینده قرار دهید تا کانال‌های برگشتی طبیعی یا گفتار همپوشانی ایجاد شود بدون اینکه برای هر واکنش به نوبت جداگانه‌ای تقسیم شود.

• تبادلات کوتاه پشت‌پرده: واکنش‌های کوتاه شنونده ( |oh hmm| ، |oh really?| ، |absolutely| ) را درون نوبت گوینده فعال قرار دهید:
  • نوبت اول (گوینده الف): "So the launch is Thursday |oh hmm| Are we actually ready?"
  • نوبت دوم (گوینده ب): "Ready enough |oh really?| The last blocker cleared this morning."
  • نوبت سوم (گوینده الف): "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 خودداری کنید. در عوض، یک صدای منطقه‌ای را از Extended Voice Library انتخاب کنید یا با Voice design یکی ایجاد کنید.

گردش کار توصیه شده

1. یک بار شخصیت را بسازید: شخصیت خود را در طراحی صدا ایجاد کنید یا یک صدای منطقه‌ای از کتابخانه صدای توسعه‌یافته انتخاب کنید که با زبان و شخصیت هدف شما مطابقت داشته باشد.
2. متن‌های گفتاری طبیعی با ناروانی‌ها بنویسید: برای حداکثر طبیعی بودن، text را به صورت یک متن گفتاری واقعی بنویسید - از جمله ناروانی‌های مکالمه طبیعی و تردیدها (برای مثال، "Oh uh yeah I think... hm, so that's interesting" ).
3. ابتدا TTS ساده را آزمایش کنید: ابتدا رونوشت خود را با یک فیلد style خالی ترکیب کنید - اکثر درخواست‌ها اصلاً نیازی به دستورالعمل style ندارند.
4. فقط برای تغییرات جزئی، از style کوتاه استفاده کنید: فقط برای نوبت‌هایی که نیاز به تنظیم خاصی در نحوه‌ی ارائه دارند، از یک رشته‌ی style مختصر (مانند "casual, friendly" یا "muttering, then reassuring" ) استفاده کنید و وقتی می‌خواهید خط مبنای ثابتی داشته باشید، دقیقاً از همان رشته‌ی کوتاه در نوبت‌های مختلف استفاده کنید.

دیالوگ‌های چند نوبتی و عوامل صوتی

هنگام ساخت عامل‌های صوتی مکالمه‌ای بلادرنگ یا برنامه‌های چند نوبتی:

• همزمان با رسیدن تکه‌های متن LLM ، در هر نوبت یک فراخوانی TTS انجام دهید.
• اجازه دهید voice پیکربندی‌شده (صدای از پیش ساخته شده، voice_... طراحی شده، یا voice_... تکثیر شده / voicekey_... ) هویت گوینده را در طول نوبت‌ها حمل کند - هرگز یک شخصیت طولانی را در هر نوبت دوباره ارسال نکنید.
• فیلد style هر نوبت را خالی بگذارید، یا یک رشته کوتاه و ثابت (مانند "casual, friendly" ) برای کل مکالمه ارسال کنید.
• به جای اینکه به دنبال سبک‌های قوی‌تر باشید، پاسخ‌های طولانی اپراتور را به نوبت‌های کوتاه‌تر تقسیم کنید.

تولید گفتار استریمینگ

شما می‌توانید صدای تولید شده را همزمان با سنتز شدن توسط مدل، پخش کنید. برخلاف درخواست‌های تک‌فایلی (که یک فایل WAV کامل با سرآیند RIFF را برمی‌گردانند)، درخواست‌های پخش، به طور پیش‌فرض تکه‌های PCM خطی ۱۶ بیتی علامت‌دار little-endian بدون سرآیند ( AUDIO_L16 / audio/L16;codec=pcm;rate=24000 ، 24 kHz، mono) خام بدون سرآیند را برمی‌گردانند، بنابراین تکه‌های صدا می‌توانند بدون سرآیندهای کانتینر، پخش یا به طور مداوم به هم متصل شوند:

from google import genai

client = genai.Client()

response_stream = client.models.generate_content_stream(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {"style": "cheerful and friendly"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "voice_config": {"voice": "Kore"}
        },
    },
)

for chunk in response_stream:
    try:
        data = chunk.candidates[0].content.parts[0].inline_data.data
        # data contains raw PCM bytes (24kHz, 1-channel, 16-bit)
    except (IndexError, AttributeError):
        pass

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

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

   const responseStream = await ai.models.generateContentStream({
      model: 'gemini-3.8-flash-tts',
      contents: [{
         role: 'user',
         parts: [{
            text: 'Have a wonderful day!',
            speechMetadata: { style: 'cheerful and friendly' },
         }],
      }],
      config: {
         responseModalities: ['AUDIO'],
         speechConfig: {
            voiceConfig: { voice: 'Kore' },
         },
      },
   });

   for await (const chunk of responseStream) {
      const data = chunk.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
      if (data) {
         const audioBuffer = Buffer.from(data, 'base64');
         // Process the audio buffer
      }
   }
}
await main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-tts:streamGenerateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "contents": [{
          "role": "user",
          "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {
              "style": "cheerful and friendly"
            }
          }]
        }],
        "generationConfig": {
          "responseModalities": ["AUDIO"],
          "speechConfig": {
            "voiceConfig": {
              "voice": "Kore"
            }
          }
        }
    }'

فرمت‌های خروجی صدا

مدل‌های Gemini 3.8 TTS بسته به اینکه درخواست تکی یا استریم باشد، از فرمت‌های صوتی پیش‌فرض متفاوتی استفاده می‌کنند:

• درخواست‌های تک‌بعدی ( models.generate_content ): صدای کامل WAV ( AUDIO_WAV ) را با یک هدر RIFF (24 کیلوهرتز، مونو، PCM با علامت ۱۶ بیتی little-endian) برمی‌گرداند. می‌توانید بایت‌های صوتی رمزگشایی شده را مستقیماً در یک فایل .wav بنویسید بدون اینکه به صورت دستی یک کانتینر WAV اضافه کنید.
• درخواست‌های استریمینگ ( models.generate_content_stream / streamGenerateContent ): به طور پیش‌فرض تکه‌های خام Linear PCM ( AUDIO_L16 ) بدون هدر (24 کیلوهرتز، مونو، 16 بیتی علامت‌دار little-endian PCM) را برمی‌گرداند تا تکه‌ها بتوانند به طور مداوم و بدون هدرهای کانتینر روی هر تکه، استریم یا به هم متصل شوند.

شما می‌توانید با استفاده از generationConfig.responseFormat.audio ، کدگذاری صدای خروجی و نرخ نمونه‌برداری را تغییر دهید:

همچنین می‌توانید به صورت اختیاری sampleRate ) را مشخص کنید (برای مثال، 24000 ، 16000 یا 8000 هرتز؛ پیش‌فرض 24000 هرتز است).

مثال زیر درخواست PCM خام ۱۶ بیتی بدون هدر ( AUDIO_L16 ) با فرکانس ۲۴ کیلوهرتز را می‌دهد:

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {"style": "cheerful and friendly"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "response_format": {
            "audio": {
                "mime_type": "AUDIO_L16",
                "sample_rate": 24000,
            }
        },
        "speech_config": {
            "voice_config": {"voice": "Kore"}
        },
    },
)

data = response.candidates[0].content.parts[0].inline_data.data
with open("out.pcm", "wb") as f:
    f.write(data)

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

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

   const response = await ai.models.generateContent({
      model: 'gemini-3.8-flash-tts',
      contents: [{
         role: 'user',
         parts: [{
            text: 'Have a wonderful day!',
            speechMetadata: { style: 'cheerful and friendly' },
         }],
      }],
      config: {
         responseModalities: ['AUDIO'],
         responseFormat: {
            audio: {
               mimeType: 'AUDIO_L16',
               sampleRate: 24000,
            },
         },
         speechConfig: {
            voiceConfig: { voice: 'Kore' },
         },
      },
   });

   const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
   const audioBuffer = Buffer.from(data, 'base64');

   fs.writeFileSync('out.pcm', audioBuffer);
}
await main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-tts:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "contents": [{
          "role": "user",
          "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {
              "style": "cheerful and friendly"
            }
          }]
        }],
        "generationConfig": {
          "responseModalities": ["AUDIO"],
          "responseFormat": {
            "audio": {
              "mimeType": "AUDIO_L16",
              "sampleRate": 24000
            }
          },
          "speechConfig": {
            "voiceConfig": {
              "voice": "Kore"
            }
          }
        }
    }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | \
          base64 --decode > out.pcm

محدودیت‌ها

• مدل‌های TTS ورودی‌های فقط متنی را می‌پذیرند و خروجی‌های فقط صوتی تولید می‌کنند.
• تولید چند گوینده با یک درخواست ( multiSpeakerVoiceConfig ) حداکثر از ۲ گوینده با استفاده از صداهای از پیش ساخته شده پشتیبانی می‌کند. برای ترکیب صداهای سفارشی طراحی شده ( voice_... ) یا تکرار شده ( voice_... / voicekey_... ) در گفتگوی چند کاراکتری، نوبت هر گوینده را به صورت جداگانه ترکیب کنید. از آنجا که درخواست‌های تکی به طور پیش‌فرض audio/wav را با یک هدر RIFF 44 بایتی برمی‌گردانند، قبل از اتصال فریم‌های صوتی PCM 24 کیلوهرتز، PCM خام ( AUDIO_L16 ) را درخواست کنید یا هدر WAV را از هر نوبت حذف کنید.
• محدودیت‌های ذخیره‌سازی صدای سفارشی و TTL:
  • صداهای دارای وضعیت ( store=True ، فراخوانی یا تکرار): حداکثر ۲۰۰ صدا در هر پروژه با TTL (زمان ماندگاری) ۱ ساله .
  • کلیدهای صوتی بدون وضعیت ( store=False ، voicekey_... ): زمان ماندگاری ۷ روزه (TTL ).
• برای اطلاع از پوشش زبان‌ها، بخش زبان‌های پشتیبانی‌شده را مرور کنید.

قدم بعدی چیست؟

• با طراحی صدا، شخصیت‌های صوتی سفارشی از زبان طبیعی ایجاد کنید.
• صدای گوینده موجود را در Voice replication تکرار کنید.
• مشخصات مدل‌ها را در صفحات مربوط به مدل‌های Gemini 3.8 Flash TTS و Gemini 3.8 Flash-Lite TTS مقایسه کنید.
• با Live API، صدای دو طرفه تعاملی را کاوش کنید.