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

يمكن لـ 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 المدرَجة في قسم النماذج المتوافقة، والترقية إلى أحدث إصدار من حزمة تطوير البرامج (SDK) الخاصة بالذكاء الاصطناعي التوليدي من Google (الإصدار google-genai >= 2.25.0 من Python أو الإصدار @google/genai >= 2.24.0 من JavaScript/TypeScript) أو استخدام واجهة برمجة التطبيقات REST API. للحصول على أفضل النتائج، راجِع حالات استخدام كل نموذج لاختيار النموذج الأفضل لعبء العمل لديك.

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

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

لتحويل النص إلى محتوى صوتي بصوت متحدث واحد باستخدام نماذج تحويل النص إلى كلام من Gemini 3.8، مرِّر النص الحرفي في input، وأرفِق التنسيق على مستوى الجملة باستخدام التعليق التوضيحي speech_metadata، واضبط صوتك في generation_config.speech_config. يمكنك اختيار صوت من خيارات الصوت المضمّنة أو "مكتبة الأصوات الموسّعة" (GET /v1beta/voices) أو معرّف تصميم الصوت المخصّص (voice_...) أو معرّف نسخ الصوت (voice_... أو voicekey_... الاختياري بدون حالة).

يحفظ هذا المثال الناتج الصوتي التلقائي بتنسيق WAV ‏ (audio/wav) من النموذج مباشرةً في ملف:

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

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();

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

في حزمتَي تطوير البرامج (SDK) لكل من Python وJavaScript، يمكنك استرداد البيانات الصوتية التي تم إنشاؤها باستخدام السمة المريحة interaction.output_audio، والتي تعرض آخر مجموعة صوتية تم إنشاؤها (في ردود REST JSON الأولية، يتم تخزين الصوت بترميز base64 في steps[].content[].data). للحصول على تفاصيل حول السمات المريحة، يُرجى الاطّلاع على نظرة عامة على التفاعلات.

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

بالنسبة إلى الحوارات التي يشارك فيها عدة متحدثين، يمكنك ضبط متحدثَين في speech_config.speakers وتمرير كل دور كعنصر نصي منفصل مع تعليق توضيحي speech_metadata يحدّد speaker وstyle اختياري على مستوى الدور. يُرجى العِلم أنّ السمة speech_config تقبل مصفوفة ([{"voice": "..."}]) لإنشاء صوت متحدث واحد، وتقبل كائنًا ({"speakers": [...]}) لإنشاء صوت عدة متحدثين:

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

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();

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 مع الحقل 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...").

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

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

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();

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. على عكس الطلبات الأحادية (التي تعرض ملف WAV كاملاً مع عنوان RIFF)، تعرض طلبات البث المباشر تلقائيًا أجزاء PCM خطية أولية بتنسيق little-endian وبدقة 16 بت وبدون عناوين (audio/l16، 24 كيلو هرتز، أحادي)، ما يتيح تشغيل أجزاء الصوت أو ربطها بشكل متواصل بدون عناوين الحاويات.

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)

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();

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

• طلبات أحادية (stream=False): تعرض هذه الطلبات ملف WAV (audio/wav) صوتيًا كاملاً مع عنوان RIFF عادي (24 كيلو هرتز، أحادي، 16 بت، PCM صغير الحجم). يمكنك حفظ وحدات بايت الصوت التي تم فك ترميزها مباشرةً في ملف .wav بدون إضافة عنوان WAV يدويًا.
• طلبات البث (stream=True): يتم عرض أجزاء Linear PCM الأولي غير المضمّن في رأس (audio/l16) (بمعدل 24 كيلو هرتز، أحادي القناة، 16 بت، PCM صغير الترتيب) تلقائيًا، ما يتيح بث الأجزاء أو ربطها بشكل متواصل بدون رؤوس حاويات في كل جزء.

لطلب ترميز صوتي أو معدّل البيانات في الملف الصوتي مختلفَين، اضبط mime_type وsample_rate الاختياري داخل response_format:

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

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

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();

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" }
      ]
    }
  }'

خيارات الصوت

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

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

* تمديد مدة الصلاحية: تتم إعادة ضبط فترة الاحتفاظ بالبيانات التي تبلغ عامًا واحدًا في كل مرة يتم فيها استخدام الصوت بشكل نشط (إما من خلال تحويل النص إلى كلام باستخدام الصوت أو استخدامه كصوت أساسي لإعادة المزج). يتم تلقائيًا حذف الأصوات التي لا يتم استخدامها لمدة عام واحد.

الأصوات المُعدّة مسبقًا

مكتبة الأصوات الموسّعة والفلترة

بالإضافة إلى الأصوات الـ 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 لتحويل النص إلى كلام إلى Gemini 3.8 لتحويل النص إلى كلام:

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. تصميم شخصيات مسبقًا باستخدام "تصميم الصوت": استبدِلوا الفقرات المتعددة أو كتل "Audio Profile" أو "Director's Notes" بصوت مخصّص تم إنشاؤه في تصميم الصوت، ثمّ استخدِموا معرّف voice_... في طلبات تحويل النص إلى كلام مع الحد الأدنى من سلاسل style أو عدم استخدامها.
5. احتساب الناتج التلقائي بتنسيق WAV (audio/wav) في الطلبات الأحادية: على عكس gemini-3.1-flash-tts-preview ونماذج تحويل النص إلى كلام الأقدم (التي كانت تعرض بشكل تلقائي بيانات PCM أولية audio/l16 بدون عنوان)، تعرض خدمة تحويل النص إلى كلام من Gemini 3.8 بشكل تلقائي صوت WAV (audio/wav) مع عنوان RIFF عادي للطلبات الأحادية.
   • إذا كان الرمز البرمجي يغلّف وحدات بايت PCM الأولية في رأس WAV (على سبيل المثال، باستخدام الوحدة wave أو ffmpeg في Python)، عليك إزالة غلاف الرأس اليدوي وكتابة وحدات البايت التي تم إرجاعها مباشرةً في ملف .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). يُرجى الاطّلاع على تنسيقات إخراج الصوت.

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

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

القيود

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

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

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