إنشاء محتوى باستخدام تكنولوجيا "تحويل النص إلى كلام"

يمكن لواجهة Gemini API تحويل النص المدخل إلى صوت أحادي أو متعدّد المتحدثين باستخدام إمكانات تحويل النص إلى كلام (TTS) في Gemini. يمكن التحكّم في عملية إنشاء المحتوى الصوتي من النص، ما يعني أنّه يمكنك الجمع بين البيانات الوصفية المنظَّمة الخاصة بالمنعطفات (speech_metadata) وعلامات الصوت المضمّنة لتوجيه الأسلوب واللهجة والسرعة والنبرة في المحتوى الصوتي.

تختلف إمكانية تحويل النص إلى كلام عن إمكانية إنشاء الكلام المقدَّمة من خلال Live API، وهي مصمَّمة لتوفير تجربة تفاعلية للمحتوى الصوتي غير المنظَّم، وللمدخلات والمخرجات المتعدّدة الوسائط. في حين تتفوّق واجهة Live API في سياقات المحادثات الديناميكية، تم تصميم ميزة تحويل النص إلى كلام من خلال 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 مدرَج في قسم النماذج المتوافقة. للحصول على أفضل النتائج، راجِع مقالة حالات استخدام كل نموذج لاختيار النموذج الأنسب لعبء العمل.

ننصحك بتجربة نماذج تحويل النص إلى كلام من Gemini في AI Studio قبل البدء في إنشاء التطبيق.

تحويل النص إلى كلام بصوت شخص واحد

لتحويل النص إلى صوت أحادي المتحدث باستخدام نماذج تحويل النص إلى كلام من 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

تحويل النص إلى كلام لعدة متحدثين

بالنسبة إلى الحوارات التي تضم عدة متحدثين، اضبط متحدثَين في 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 مع الحقل 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...").

يمكنك الاطّلاع على دليل الطلبات لمعرفة أفضل الممارسات الشاملة.

خيارات الصوت

يتيح الإصدار 3.8 من ميزة "تحويل النص إلى كلام" في Gemini أربع طرق لاختيار الأصوات أو إنشائها:

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 ثابت تلقائيًا أو 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"

اللغات المتاحة

ترصد نماذج تحويل النص إلى كلام لغة الإدخال تلقائيًا. يتوافق 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 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.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_... نفسه في طلبات تحويل النص إلى كلام مع الحد الأدنى من سلاسل style أو بدونها.
3. استخدام جمل حوارية منظَّمة: بالنسبة إلى الحوارات التي تضمّ عدة متحدثين، مرِّر part واحدًا لكل جملة حوارية مع speech_metadata.speaker بدلاً من تضمين البادئات Speaker: ... داخل فقرة نصية واحدة.
4. استخدام أقواس الزاوية لعلامات الصوت المضمّنة: استخدِم أقواس الزاوية (<laugh> و<sigh> و<cough> و<breath> و<short pause>) للإشارة إلى الأصوات البشرية والفواصل الزمنية. تجنَّبوا علامات التأثيرات الصوتية غير الصوتية (مثل التصفيق أو الضربات).
5. مراعاة إخراج WAV (AUDIO_WAV) التلقائي في الطلبات الأحادية: على عكس gemini-3.1-flash-tts-preview (الذي كان يعرض PCM الأولي بدون عنوانAUDIO_L16 تلقائيًا)، تعرض نماذج تحويل النص إلى صوت في Gemini 3.8 صوت WAV كامل (AUDIO_WAV) مع عنوان RIFF (بتردد 24 كيلو هرتز، أحادي القناة، PCM بمعدل 16 بت) في الطلبات الأحادية:
   • إذا كان الرمز البرمجي يضمّن سابقًا وحدات بايت PCM أولية في عنوان WAV (على سبيل المثال، باستخدام الوحدة wave في Python أو الحزمة wav في Node)، عليك إزالة غلاف العنوان اليدوي وكتابة وحدات بايت الصوت التي تم فك ترميزها مباشرةً في ملف .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). اطّلِع على تنسيقات مصدر إخراج الصوت.

الدليل الإرشادي لكتابة الطلبات

تتعامل نماذج تحويل النص إلى كلام (TTS) في Gemini 3.8 مع النص المدخل على أنّه نص مطابق تمامًا. على عكس نماذج المعاينة السابقة التي كانت تتضمّن إرشادات الأداء في نص عادي، يفصل الإصدار 3.8 من Gemini لتحويل النص إلى كلام الإرشادات المستمرة على مستوى الدور (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.
• السرعة على مستوى الجملة: اضبط "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.

العبارات الصوتية والأصوات غير الكلامية

ضَع الأصوات البشرية غير الكلامية في السطر باستخدام أقواس زاوية (<...>) في الموضع الدقيق الذي يجب أن يصدر فيه الصوت. تشمل العلامات الصوتية المقترَحة ما يلي:

قنوات التواصل الخلفية وتداخل الكلام

في الحوارات التي تضم عدة متحدثين، ضَع ردود المستمعين بين علامات الأنابيب (|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_... مخصّصة وثابتة، ثم استخدِم معرّف الصوت هذا في طلبات تحويل النص إلى كلام.
• الاعتماد على المرجع الصوتي لتحقيق الثبات (حذف التعليمات الوصفية): تم تدريب نماذج تحويل النص إلى كلام في الإصدار 3.8 من Gemini على الاعتماد على المرجع الصوتي أولاً. لا تُدرِج تعليمات تطلب من النموذج الحفاظ على ثبات الصوت (مثل "do not switch speaker identity" أو "maintain identical timbre")، لأنّ النص الإضافي في الطلب يزيد من الانحراف. تجاهل تعليمات الأسلوب غير الضرورية والسماح للنموذج بالتنوّع بشكل طبيعي حول النقطة الثابتة التي توفّرها المرجع الصوتي.
• لا تحاول تغيير سمات المتحدث غير القابلة للتغيير في style: تجنَّب وضع العمر أو الجنس أو الأسماء أو التغييرات الدائمة في اللهجة في speech_metadata.style. بدلاً من ذلك، اختَر صوتًا إقليميًا من "مكتبة الأصوات الموسّعة" أو أنشئ صوتًا باستخدام تصميم الصوت.

سير العمل المقترَح

1. إنشاء الشخصية مرة واحدة: أنشئ شخصيتك في تصميم الصوت أو اختَر صوتًا مناسبًا لمنطقتك من "مكتبة الأصوات الموسّعة" يتطابق مع لغتك المستهدَفة وشخصيتك.
2. كتابة نصوص طبيعية تتضمّن أخطاء في الكلام: للحصول على أعلى مستوى من الطبيعية، اكتب text كنص حقيقي يتضمّن أخطاء طبيعية في الكلام وتردّدًا (على سبيل المثال، "Oh uh yeah I think... hm, so that's interesting").
3. اختبار تحويل النص إلى كلام العادي أولاً: يمكنك تركيب النص باستخدام حقل style فارغ أولاً، إذ إنّ معظم الطلبات لا تحتاج إلى أي تعليمات style على الإطلاق.
4. إضافة طلبات قصيرة style للتعديلات فقط: أضِف سلسلة style موجزة (مثل "casual, friendly" أو "muttering, then reassuring") فقط للعبارات التي تحتاج إلى تعديل محدّد في طريقة العرض، وأعِد استخدام هذه السلسلة القصيرة نفسها في العبارات عندما تريد الحصول على أساس ثابت.

الوكلاء الحواريون والصوتيون في المحادثات المترابطة

عند إنشاء وكلاء صوتيين حواريين في الوقت الفعلي أو تطبيقات محادثة مترابطة، يجب مراعاة ما يلي:

• إجراء مكالمة واحدة لتحويل النص إلى كلام في كل مرة عند وصول أجزاء النص من النموذج اللغوي الكبير
• اسمح لـ voice الذي تم إعداده (مُنشأ مسبقًا أو مصمّم voice_... أو مكرّر voice_... / voicekey_...) بنقل هوية المتحدث خلال المحادثات، ولا تعِد إرسال شخصية طويلة في كل محادثة.
• اترك الحقل style الخاص بكلّ دور فارغًا، أو أرسِل سلسلة ثابتة قصيرة واحدة (مثل "casual, friendly") للمحادثة بأكملها.
• قسِّم ردود الوكيل الطويلة إلى ردود أقصر بدلاً من استخدام طلبات ذات أسلوب أقوى.

إنشاء محتوى صوتي للبث المباشر

يمكنك بث الصوت الذي تم إنشاؤه أثناء توليفه بواسطة النموذج. على عكس الطلبات الأحادية (التي تعرض ملف WAV كاملاً مع عنوان RIFF)، تعرض طلبات البث أجزاءً من بيانات PCM خطية أولية موقعة ذات 16 بت بدون عناوين (AUDIO_L16 / audio/L16;codec=pcm;rate=24000، 24 كيلو هرتز، أحادي) تلقائيًا، وبالتالي يمكن تشغيل أجزاء الصوت أو ربطها بشكل مستمر بدون عناوين الحاويات:

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 تنسيقات صوتية تلقائية مختلفة حسب ما إذا كان الطلب أحاديًا أو متواصلاً:

• طلبات أحادية (models.generate_content): تعرض صوت WAV (AUDIO_WAV) كاملاً مع عنوان RIFF (بمعدّل 24 كيلوهرتز، أحادي القناة، و16 بت بتنسيق PCM مع توقيع little-endian). يمكنك كتابة وحدات بايت الصوت التي تم فك ترميزها مباشرةً في ملف .wav بدون إضافة حاوية WAV يدويًا.
• طلبات البث (models.generate_content_stream / streamGenerateContent): يتم عرض أجزاء Linear PCM الأولية بدون عناوين (AUDIO_L16) (بمعدل 24 كيلو هرتز، أحادي القناة، و16 بت بتنسيق PCM الصغير ذي الإشارة) تلقائيًا، ما يتيح بث الأجزاء أو ربطها بشكل متواصل بدون عناوين حاوية في كل جزء.

يمكنك تجاهل ترميز الصوت ومعدّل البيانات في الملف الصوتي باستخدام generationConfig.responseFormat.audio:

يمكنك أيضًا تحديد sampleRate بشكل اختياري (على سبيل المثال، 24000 أو 16000 أو 8000 هرتز، ويتم ضبط القيمة التلقائية على 24000 هرتز).

يطلب المثال التالي بيانات PCM أولية 16 بت بدون عنوان (AUDIO_L16) بمعدل 24 كيلوهرتز:

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

القيود

• تقبل نماذج تحويل النص إلى كلام مدخلات نصية فقط وتنتج مخرجات صوتية فقط.
• تتيح ميزة إنشاء مقاطع صوتية لعدة متحدّثين بطلب واحد (multiSpeakerVoiceConfig) استخدام ما يصل إلى متحدّثَين باستخدام أصوات معدّة مسبقًا. لدمج أصوات مصمَّمة خصيصًا (voice_...) أو مكرّرة (voice_... / voicekey_...) في حوار يتضمّن عدة شخصيات، يجب تركيب صوت كل متحدث على حدة. بما أنّ الطلبات الأحادية تعرض audio/wav مع عنوان RIFF يبلغ 44 بايت تلقائيًا، اطلب بيانات PCM أولية (AUDIO_L16) أو أزِل عنوان WAV من كل دورة قبل ربط إطارات الصوت PCM التي تبلغ 24 كيلو هرتز.
• حدود مساحة تخزين الصوت المخصّص وTTL:
  • الأصوات التي تحتفظ بحالتها (store=True، التي يتم إنشاؤها بناءً على طلب أو نسخها): يمكن استخدام 200 صوت كحد أقصى لكل مشروع مع مدة بقاء تبلغ عامًا واحدًا.
  • مفاتيح الصوت غير المرتبطة بحالة (store=False، voicekey_...): مدة البقاء (TTL) لمدة 7 أيام
• راجِع قسم اللغات المتاحة للاطّلاع على اللغات التي تغطيها الخدمة.

الخطوات التالية

• إنشاء شخصيات صوتية مخصّصة من اللغة الطبيعية باستخدام تصميم الصوت
• تقليد صوت متحدث حالي في تقليد الصوت
• يمكنك مقارنة مواصفات النماذج في صفحات Gemini 3.8 Flash لتحويل النص إلى كلام وGemini 3.8 Flash-Lite لتحويل النص إلى كلام.
• استكشِف الصوت التفاعلي الثنائي الاتجاه باستخدام Live API.