Gemini Voices API

تتيح لك واجهة Voices API إنشاء أصوات مخصّصة من طلبات باللغة الطبيعية (تصميم الصوت) أو من تسجيلات صوتية مرجعية وتسجيلات موافقة المتحدّث (محاكاة الصوت)، بالإضافة إلى إمكانية إدراج الأصوات المخصّصة والمُنشأة مسبقًا واسترجاعها وإدارتها لتحويل النصوص إلى كلام.

عرض بتنسيق Markdown عرض مواصفات OpenAPI

CreateVoice

post https://generativelanguage.googleapis.com/v1beta/voices

تنشئ هذه السمة صوتًا مخصّصًا من خلال طلب باللغة الطبيعية (‎`VOICE_TYPE_PROMPTED`‎) أو من خلال تسجيلات صوتية مرجعية مع الحصول على موافقة (‎`VOICE_TYPE_REPLICATED`‎).

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

store boolean  (اختياري)

اختيارية: تحديد ما إذا كان سيتم الاحتفاظ بالصوت الذي تم إنشاؤه وإدارته بواسطة Google * عند ضبط القيمة على `true`، تخزّن Google الصوت وتعرض `Voice.id` (على سبيل المثال، `voice_abc123def456`)، ويمكن إدارة هذا الصوت من خلال `GetVoice` و`ListVoices` و `DeleteVoice` والإشارة إليه باستخدام المعرّف في طلبات التوليف. تخضع المشاريع لحدّ أقصى من حصة الصوت النشط المخزّن، وفي حال تجاوز الحصة، يتم عرض الخطأ `RESOURCE_EXHAUSTED`. * عند ضبط القيمة على `false` (الإعداد التلقائي)، لا تخزّن Google الصوت ويتم عرض `Voice.key` (مثلاً، `voicekey_...`) للتخزين والتركيب من جهة العميل. لا يتم الاحتفاظ بحقول البيانات الوصفية الاختيارية الخاصة بالاكتشاف في `voice` أو عرضها عندما تكون قيمة `store` هي `false`. * يجب أن تكون القيمة `true` عندما تكون قيمة `voice.type` هي `"prompted"` (وإلا سيحدث خطأ `INVALID_ARGUMENT`).

voice Voice  (مطلوبة)

الحقل مطلوب. الصوت المطلوب استخدامه لإنشاء المحتوى ‫`voice.model` هو حقل اختياري. وفي حال حذفه، تختار الخدمة نموذج إنشاء الصوت التلقائي. يتم تجاهل الحقول المخصّصة للإخراج فقط في Voice‏ (id وkey وexpire_time وusage) في حال ضبطها.

الردّ

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

accent string  (اختياري)

اختيارية: واصف اللهجة الإقليمية (مثلاً "أمريكية" أو "بريطانية")

context string  (اختياري)

اختيارية: سياق الاستخدام أو النطاق الأمثل (مثل "محادثة" أو "كتاب مسموع" أو "أخبار")

الوصف string  (اختياري)

اختيارية: ملخّص وصفي لنبرة الصوت والشخصية والأسلوب

display_name string  (اختياري)

اختيارية: اسم العرض المقدَّم من المستخدم لصوت مخزَّن (`store = true`)، أو اسم الكتالوج لصوت مُعدّ مسبقًا

expire_time string  (اختياري)

النتائج فقط. الطابع الزمني الذي تنتهي فيه صلاحية الصوت المخصّص المخزّن (`store = true`) أو مفتاح الصوت المنسوخ (`store = false`). يتم ضبط القيمة على "غير مضبوط" لأصوات الكتالوجات المسبقة الإنشاء (`"prebuilt"`) التي لا تنتهي صلاحيتها.

gender string  (اختياري)

اختيارية: عرض الجنس المتصوّر للصوت (مثلاً "أنثى" أو "ذكر" أو "محايد").

id string  (اختياري)

النتائج فقط. المعرّف الفريد للصوت * بالنسبة إلى الأصوات المخصّصة التي تديرها Google‏ (`store = true`)، يكون هذا المعرّف من إنشاء النظام ويبدأ بالبادئة `voice_` (مثلاً، `voice_abc123def456`). مرِّر `voices/{id}` كـ `name` في `GetVoice` و `DeleteVoice`، ومرِّر `{id}` مباشرةً إلى `SpeechConfig.voice_config.voice` (أو `SpeechConfig.voice`) أثناء تركيب الكلام. * بالنسبة إلى الأصوات المضمّنة في الكتالوج (`"prebuilt"` التي تعرضها الدالة `ListVoices`)، هذا هو اسم المتحدث (على سبيل المثال، `Puck` أو `Charon`). * يتم ضبط القيمة على "غير محدّد" عند استدعاء الدالة `CreateVoice` مع ضبط `store = false`.

key string  (اختياري)

النتائج فقط. مفتاح تكرار الصوت الذي يديره العميل (مع البادئة `voicekey_`). يتم عرضه فقط من خلال `CreateVoice` عندما يكون `type` هو `"replicated"` و `store` هو `false`. مرِّر هذا المفتاح إلى `SpeechConfig.voice_config.voice` (أو `SpeechConfig.voice`) أثناء تركيب الكلام.

language_code سلسلة  (اختيارية)

اختيارية: علامة اللغة الأساسية وفق المعيار BCP-47 (مثل "en-US" أو "fr-FR").

model string  (اختياري)

اختيارية: النموذج المستخدَم لتصميم الصوت أو تكراره في حال عدم تضمينها في `CreateVoice`، سيتم تلقائيًا استخدام أحدث نموذج متوافق لتصميم الصوت. يتم عرض هذه السمة في ردود `CreateVoice` و`GetVoice` و `ListVoices` للأصوات المخصّصة (`"prompted"` و `"replicated"`)، ويتم ضبطها على "غير محدّد" للأصوات `"prebuilt"`. يمكن تركيب الأصوات التي تم إنشاؤها باستخدام أي نموذج تركيب متوافق مع ميزة تحويل النص إلى كلام.

persona string  (اختياري)

اختيارية: الشخصية المقصودة أو النموذج الأصلي للشخصية (مثل "ودود ولطيف" أو "راوٍ").

pitch Pitch  (اختياري)

اختيارية: تصنيف درجة الصوت

القيم المحتملة

  • low

    نبرة صوت منخفضة

  • medium

    صوت متوسط الحدة

  • high

    نبرة صوت عالية

تمت المطالبة PromptedVoice  (اختياري)

مَعلمات إنشاء الصوت بناءً على طلب مطلوبة في `CreateVoice` عندما تكون قيمة `type` هي `"prompted"`. يتم عرضها في ردود `CreateVoice` و`GetVoice` و `ListVoices` للأصوات التي تم إنشاؤها بناءً على طلب.

مَعلمات لإنشاء الصوت بناءً على طلب مطلوبة في `CreateVoice` عندما تكون قيمة `type` هي `"prompted"`. يتم عرضها في ردود `CreateVoice` و`GetVoice` و `ListVoices` للأصوات التي تم إنشاؤها بناءً على طلب.

الحقول

input string  (اختياري)

الحقل مطلوب. طلب باللغة الطبيعية يصف الصوت المطلوب، مثل "صوت رجالي عميق وقوي لغول شرير ضخم في منتصف العمر"

region_code string  (اختيارية)

اختيارية: رمز المنطقة الجغرافية وفقًا لمعيار ISO 3166-1 alpha-2 أو معيار الأمم المتحدة M.49 (مثل "US" أو "GB" أو "001")

sample_audio AudioData  (اختياري)

النتائج فقط. محتوى صوتي تجريبي (محتوى صوتي من طلب باستخدام آلة المزج) تم إنشاؤه لصوت مطلوب يتم ملء هذا الحقل فقط في ردود `CreateVoice` و`GetVoice` عندما تكون قيمة `type` هي `"prompted"`، ويتم إلغاء ضبطه في ردود `ListVoices` وفي حال كانت قيمة `type` هي `"replicated"` أو `"prebuilt"`.

حمولة الصوت المستخدَمة لإنشاء الصوت

الحقول

data string  (اختياري)

الحقل مطلوب. وحدات البايت الخاصة بالصوت الخام

mime_type string  (اختيارية)

الحقل مطلوب. نوع MIME الخاص بـ IANA لبيانات الصوت (على سبيل المثال، `audio/wav` أو `audio/mpeg`).

type VoiceType  (اختياري)

الحقل مطلوب. تمثّل هذه السمة نوع الصوت. في `CreateVoice`، يجب أن تكون القيمة `"replicated"` أو `"prompted"`. في ردود `ListVoices`، يمكن أن تكون القيمة أيضًا `"prebuilt"`.

القيم المحتملة

  • replicated

    صوت مخصّص تم إنشاؤه من عيّنة صوتية مرجعية وتسجيل موافقة المتحدث

  • prompted

    صوت مخصّص تم إنشاؤه من طلب نصي باللغة الطبيعية

  • prebuilt

    صوت نظام مضمّن من كتالوج الأصوات في Google (مثل `Puck` أو `Charon`)، ويتم عرضه في الردود، ولا يمكن تحديده كنوع في `CreateVoice`.

usage Usage  (اختياري)

النتائج فقط. إحصاءات استخدام الرموز المميزة لطلب إنشاء الصوت يتم ملء هذا الحقل فقط في ردّ `CreateVoice` عندما يكون `type` هو `"prompted"`، ويكون غير مضبوط في `"replicated"` وفي ردود `GetVoice` و `ListVoices`.

إحصاءات حول استخدام الرمز المميّز لطلب التفاعل.

الحقول

cached_tokens_by_modality array (ModalityTokens)  (اختياري)

تفاصيل استخدام الرموز المميزة المخزّنة مؤقتًا حسب طريقة العرض

عدد الرموز المميزة الخاصة بنوع ردّ واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميّزة للوسيط

grounding_tool_count array (GroundingToolCount)  (اختياري)

عدد أدوات التأسيس

عدد أدوات التأريض

الحقول

count عدد صحيح  (اختياري)

عدد أدوات التأريض.

type enum (string)  (اختياري)

نوع أداة التأسيس المرتبطة بالعدد

القيم المحتملة:

  • google_search

    تحديد المصدر من خلال "بحث Google" و"بحث الصور"، وتحديد المصدر من الويب للشركات

  • google_maps

    استخدام "خرائط Google" كمصدر

input_tokens_by_modality array (ModalityTokens)  (اختيارية)

تقسيم استخدام الرموز المميزة للإدخال حسب طريقة الإدخال

عدد الرموز المميزة الخاصة بنوع ردّ واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميزة للوسائط

output_tokens_by_modality array (ModalityTokens)  (اختيارية)

تفاصيل استخدام الرموز المميزة للناتج حسب نوع البيانات

عدد الرموز المميزة لنمط استجابة واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميزة للوسيط

tool_use_tokens_by_modality array (ModalityTokens)  (اختياري)

تفصيل لاستخدام الرموز المميزة الخاصة باستخدام الأدوات حسب نوع البيانات

عدد الرموز المميزة الخاصة بنوع ردّ واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميزة للوسيط

total_cached_tokens integer  (اختيارية)

عدد الرموز المميّزة في الجزء المخزّن مؤقتًا من الطلب (المحتوى المخزّن مؤقتًا)

total_input_tokens integer  (اختيارية)

عدد الرموز المميزة في الطلب (السياق).

total_output_tokens عدد صحيح  (اختيارية)

إجمالي عدد الرموز المميزة في جميع الردود التي تم إنشاؤها

total_thought_tokens integer  (اختيارية)

عدد الرموز المميّزة للأفكار في نماذج التفكير

total_tokens integer  (optional)

إجمالي عدد الرموز المميّزة لطلب التفاعل (الطلب + الردود + الرموز المميّزة الداخلية الأخرى).

total_tool_use_tokens عدد صحيح  (اختياري)

عدد الرموز المميزة المتوفّرة في طلبات استخدام الأدوات

مثال

مثال على الردّ

{
  "accent": "string",
  "context": "string",
  "description": "string",
  "display_name": "string",
  "expire_time": "string",
  "gender": "string",
  "id": "string",
  "key": "string",
  "language_code": "string",
  "model": "string",
  "persona": "string",
  "pitch": "low",
  "prompted": {
    "input": "string"
  },
  "region_code": "string",
  "replicated": {
    "consent_audio": {
      "data": "string",
      "mime_type": "string"
    },
    "source_audio": {
      "data": "string",
      "mime_type": "string"
    }
  },
  "sample_audio": {
    "data": "string",
    "mime_type": "string"
  },
  "type": "replicated",
  "usage": {
    "cached_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "grounding_tool_count": [
      {
        "count": 0,
        "type": "google_search"
      }
    ],
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "output_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "tool_use_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 0,
    "total_output_tokens": 0,
    "total_thought_tokens": 0,
    "total_tokens": 0,
    "total_tool_use_tokens": 0
  }
}

ListVoices

get https://generativelanguage.googleapis.com/v1beta/voices

قوائم الأصوات المخصّصة المخزّنة التي يملكها المتصل (مرتّبة من الأحدث إلى الأقدم) تليها أصوات النظام المُعدّة مسبقًا من كتالوج الأصوات في Google

مَعلمات المسار / طلب البحث

accent array (string)  (اختياري)

اختيارية: فلترة النتائج حسب وصف اللهجة (مثلاً "أمريكية" أو "بريطانية") مطابقة تامة غير حساسة لحالة الأحرف في حال تحديد قيم متعددة، يتم البحث عن تطابقات مع أي من اللهجات المحددة (OR).

context مصفوفة (سلسلة)  (اختيارية)

اختيارية: يمكنك الفلترة حسب السياق أو النطاق المقصودَين (مثل "أخبار، إعلانات تجارية"). مطابقة تامة غير حساسة لحالة الأحرف في حال تحديد قيم متعدّدة، سيتم عرض المطابقات للملفات الصوتية التي تتضمّن أيًا من السياقات المحدّدة (OR).

gender array (string)  (اختياري)

اختيارية: فلترة حسب الجنس (مثلاً "أنثى" أو "ذكر" أو "محايد") مطابقة تامة غير حساسة لحالة الأحرف في حال تحديد قيم متعددة، سيتم عرض نتائج تطابق الأصوات مع أي من الجنسين المحددين (أو).

language_code array (string)  (اختيارية)

اختيارية: يمكنك الفلترة حسب رمز اللغة BCP-47 (مثل "en-US"). مطابقة تامة غير حساسة لحالة الأحرف في حال تحديد قيم متعددة، سيتم الربط بين الأصوات وأي من رموز اللغات المحددة (OR).

page_size integer  (اختيارية)

اختيارية: الحدّ الأقصى لعدد الأصوات التي سيتم عرضها في كل صفحة قد يعرض التطبيق عددًا أقل من هذه القيمة. إذا لم يتم تحديدها، سيتم عرض 50 صوتًا كحد أقصى. الحد الأقصى للقيمة هو 1000، ويتم تحويل القيم التي تزيد عن 1000 إلى 1000.

page_token string  (اختياري)

اختيارية: رمز مميّز للصفحة تم استلامه من طلب `ListVoices` سابق. يجب تقديم هذا الرمز لاسترداد الصفحة التالية. عند تقسيم النتائج إلى صفحات، يجب أن تتطابق جميع مَعلمات طلب الفلترة (`language_code` و`region_code` و`accent` و`persona` و`context` و`gender` و`pitch` و`type` و `search`) مع الطلب الذي عرض هذه الرمز المميز، وإلا سيفشل الطلب مع ظهور الخطأ `INVALID_ARGUMENT`. وقد يتغير حجم الصفحة `page_size` بين الصفحات.

persona array (string)  (اختياري)

اختيارية: فلترة النتائج حسب الشخصية الصوتية (مثل "ودود، لطيف") مطابقة تامة غير حساسة لحالة الأحرف في حال تحديد قيم متعددة، سيتم البحث عن أصوات تطابق أيًا من الشخصيات المحددة (OR).

pitch array (string)  (اختياري)

اختيارية: الفلترة حسب درجة الصوت تقبل هذه السمة القيم "منخفض" أو "متوسط" أو "عالي" أو "PITCH_LOW" أو "PITCH_MEDIUM" أو "PITCH_HIGH" (غير حساسة لحالة الأحرف). في حال تحديد قيم متعدّدة، ستتم مطابقة الأصوات التي تتضمّن أيًا من درجات الصوت المحدّدة (OR).

region_code مصفوفة (سلسلة)  (اختيارية)

اختيارية: يمكنك الفلترة حسب رمز المنطقة ISO 3166-1 alpha-2 أو UN M.49 (مثل "US" أو "001"). مطابقة تامة غير حساسة لحالة الأحرف في حال تحديد قيم متعدّدة، يتم البحث عن تطابقات مع أي من رموز المناطق المحدّدة (OR).

search string  (اختياري)

اختيارية: طلب بحث عن سلسلة فرعية من نص حر تمت مطابقته بدون مراعاة حالة الأحرف مع كل من `display_name` و `description`. الحد الأقصى هو 2048 بايت.

type array (string)  (اختياري)

اختيارية: فلترة حسب نوع الصوت تقبل هذه السمة القيم "prebuilt" أو "replicated" أو "prompted" أو "VOICE_TYPE_PREBUILT" أو "VOICE_TYPE_REPLICATED" أو "VOICE_TYPE_PROMPTED" (غير حساسة لحالة الأحرف). في حال تحديد قيم متعددة، ستتم مطابقة الأصوات مع أي من الأنواع المحددة (أو).

الردّ

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

next_page_token string  (اختياري)

رمز مميّز يمكن إرساله كـ `page_token` لاسترداد الصفحة التالية. إذا كانت فارغة، يعني ذلك أنّه لا توجد صفحات لاحقة.

voices مصفوفة (Voice)  (اختيارية)

الأصوات من المجموعة المحدّدة

مثال

مثال على الردّ

{
  "next_page_token": "string",
  "voices": [
    {
      "accent": "string",
      "context": "string",
      "description": "string",
      "display_name": "string",
      "expire_time": "string",
      "gender": "string",
      "id": "string",
      "key": "string",
      "language_code": "string",
      "model": "string",
      "persona": "string",
      "pitch": "low",
      "prompted": {
        "input": "string"
      },
      "region_code": "string",
      "replicated": {
        "consent_audio": {
          "data": "string",
          "mime_type": "string"
        },
        "source_audio": {
          "data": "string",
          "mime_type": "string"
        }
      },
      "sample_audio": {
        "data": "string",
        "mime_type": "string"
      },
      "type": "replicated",
      "usage": {
        "cached_tokens_by_modality": [
          {
            "modality": "...",
            "tokens": 0
          }
        ],
        "grounding_tool_count": [
          {
            "count": 0,
            "type": "google_search"
          }
        ],
        "input_tokens_by_modality": [
          {
            "modality": "...",
            "tokens": 0
          }
        ],
        "output_tokens_by_modality": [
          {
            "modality": "...",
            "tokens": 0
          }
        ],
        "tool_use_tokens_by_modality": [
          {
            "modality": "...",
            "tokens": 0
          }
        ],
        "total_cached_tokens": 0,
        "total_input_tokens": 0,
        "total_output_tokens": 0,
        "total_thought_tokens": 0,
        "total_tokens": 0,
        "total_tool_use_tokens": 0
      }
    }
  ]
}

GetVoice

get https://generativelanguage.googleapis.com/v1beta/voices/{voicesId}

يحصل على صوت مخصّص مخزَّن (`store = true`) حسب اسم المورد. لا يمكن استرداد أصوات الكتالوج الجاهزة (`VOICE_TYPE_PREBUILT`) باستخدام `GetVoice`، بل يجب استخدام `ListVoices`.

مَعلمات المسار / طلب البحث

voicesId string  (مطلوبة)

الحقل مطلوب. اسم المورد الخاص بالصوت المخصّص المخزّن الذي سيتم استرجاعه (مثلاً، `voices/voice_abc123def456`).

الردّ

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

accent string  (اختياري)

اختيارية: واصف اللهجة الإقليمية (مثلاً "أمريكية" أو "بريطانية")

context string  (اختياري)

اختيارية: سياق الاستخدام أو النطاق الأمثل (مثل "محادثة" أو "كتاب مسموع" أو "أخبار")

الوصف string  (اختياري)

اختيارية: ملخّص وصفي لنبرة الصوت والشخصية والأسلوب

display_name string  (اختياري)

اختيارية: اسم العرض المقدَّم من المستخدم لصوت مخزَّن (`store = true`)، أو اسم الكتالوج لصوت مُعدّ مسبقًا

expire_time string  (اختياري)

النتائج فقط. الطابع الزمني الذي تنتهي فيه صلاحية الصوت المخصّص المخزّن (`store = true`) أو مفتاح الصوت المنسوخ (`store = false`). يتم ضبط القيمة على "غير مضبوط" لأصوات الكتالوجات المسبقة الإنشاء (`"prebuilt"`) التي لا تنتهي صلاحيتها.

gender string  (اختياري)

اختيارية: عرض الجنس المتصوّر للصوت (مثلاً "أنثى" أو "ذكر" أو "محايد").

id string  (اختياري)

النتائج فقط. المعرّف الفريد للصوت * بالنسبة إلى الأصوات المخصّصة التي تديرها Google‏ (`store = true`)، يكون هذا المعرّف من إنشاء النظام ويبدأ بالبادئة `voice_` (مثلاً، `voice_abc123def456`). مرِّر `voices/{id}` كـ `name` في `GetVoice` و `DeleteVoice`، ومرِّر `{id}` مباشرةً إلى `SpeechConfig.voice_config.voice` (أو `SpeechConfig.voice`) أثناء تركيب الكلام. * بالنسبة إلى الأصوات المضمّنة في الكتالوج (`"prebuilt"` التي تعرضها الدالة `ListVoices`)، هذا هو اسم المتحدث (على سبيل المثال، `Puck` أو `Charon`). * يتم ضبط القيمة على "غير محدّد" عند استدعاء الدالة `CreateVoice` مع ضبط `store = false`.

key string  (اختياري)

النتائج فقط. مفتاح تكرار الصوت الذي يديره العميل (مع البادئة `voicekey_`). يتم عرضه فقط من خلال `CreateVoice` عندما يكون `type` هو `"replicated"` و `store` هو `false`. مرِّر هذا المفتاح إلى `SpeechConfig.voice_config.voice` (أو `SpeechConfig.voice`) أثناء تركيب الكلام.

language_code سلسلة  (اختيارية)

اختيارية: علامة اللغة الأساسية وفق المعيار BCP-47 (مثل "en-US" أو "fr-FR").

model string  (اختياري)

اختيارية: النموذج المستخدَم لتصميم الصوت أو تكراره في حال عدم تضمينها في `CreateVoice`، سيتم تلقائيًا استخدام أحدث نموذج متوافق لتصميم الصوت. يتم عرض هذه السمة في ردود `CreateVoice` و`GetVoice` و `ListVoices` للأصوات المخصّصة (`"prompted"` و `"replicated"`)، ويتم ضبطها على "غير محدّد" للأصوات `"prebuilt"`. يمكن تركيب الأصوات التي تم إنشاؤها باستخدام أي نموذج تركيب متوافق مع ميزة تحويل النص إلى كلام.

persona string  (اختياري)

اختيارية: الشخصية المقصودة أو النموذج الأصلي للشخصية (مثل "ودود ولطيف" أو "راوٍ").

pitch Pitch  (اختياري)

اختيارية: تصنيف درجة الصوت

القيم المحتملة

  • low

    نبرة صوت منخفضة

  • medium

    صوت متوسط الحدة

  • high

    نبرة صوت عالية

تمت المطالبة PromptedVoice  (اختياري)

مَعلمات إنشاء الصوت بناءً على طلب مطلوبة في `CreateVoice` عندما تكون قيمة `type` هي `"prompted"`. يتم عرضها في ردود `CreateVoice` و`GetVoice` و `ListVoices` للأصوات التي تم إنشاؤها بناءً على طلب.

مَعلمات لإنشاء الصوت بناءً على طلب مطلوبة في `CreateVoice` عندما تكون قيمة `type` هي `"prompted"`. يتم عرضها في ردود `CreateVoice` و`GetVoice` و `ListVoices` للأصوات التي تم إنشاؤها بناءً على طلب.

الحقول

input string  (اختياري)

الحقل مطلوب. طلب باللغة الطبيعية يصف الصوت المطلوب، مثل "صوت رجالي عميق وقوي لغول شرير ضخم في منتصف العمر"

region_code string  (اختيارية)

اختيارية: رمز المنطقة الجغرافية وفقًا لمعيار ISO 3166-1 alpha-2 أو معيار الأمم المتحدة M.49 (مثل "US" أو "GB" أو "001")

sample_audio AudioData  (اختياري)

النتائج فقط. محتوى صوتي تجريبي (محتوى صوتي من طلب باستخدام آلة المزج) تم إنشاؤه لصوت مطلوب يتم ملء هذا الحقل فقط في ردود `CreateVoice` و`GetVoice` عندما تكون قيمة `type` هي `"prompted"`، ويتم إلغاء ضبطه في ردود `ListVoices` وفي حال كانت قيمة `type` هي `"replicated"` أو `"prebuilt"`.

حمولة الصوت المستخدَمة لإنشاء الصوت

الحقول

data string  (اختياري)

الحقل مطلوب. وحدات البايت الخاصة بالصوت الخام

mime_type string  (اختيارية)

الحقل مطلوب. نوع MIME الخاص بـ IANA لبيانات الصوت (على سبيل المثال، `audio/wav` أو `audio/mpeg`).

type VoiceType  (اختياري)

الحقل مطلوب. تمثّل هذه السمة نوع الصوت. في `CreateVoice`، يجب أن تكون القيمة `"replicated"` أو `"prompted"`. في ردود `ListVoices`، يمكن أن تكون القيمة أيضًا `"prebuilt"`.

القيم المحتملة

  • replicated

    صوت مخصّص تم إنشاؤه من عيّنة صوتية مرجعية وتسجيل موافقة المتحدث

  • prompted

    صوت مخصّص تم إنشاؤه من طلب نصي باللغة الطبيعية

  • prebuilt

    صوت نظام مضمّن من كتالوج الأصوات في Google (مثل `Puck` أو `Charon`)، ويتم عرضه في الردود، ولا يمكن تحديده كنوع في `CreateVoice`.

usage Usage  (اختياري)

النتائج فقط. إحصاءات استخدام الرموز المميزة لطلب إنشاء الصوت يتم ملء هذا الحقل فقط في ردّ `CreateVoice` عندما يكون `type` هو `"prompted"`، ويكون غير مضبوط في `"replicated"` وفي ردود `GetVoice` و `ListVoices`.

إحصاءات حول استخدام الرمز المميّز لطلب التفاعل.

الحقول

cached_tokens_by_modality array (ModalityTokens)  (اختياري)

تفاصيل استخدام الرموز المميزة المخزّنة مؤقتًا حسب طريقة العرض

عدد الرموز المميزة الخاصة بنوع ردّ واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميّزة للوسيط

grounding_tool_count array (GroundingToolCount)  (اختياري)

عدد أدوات التأسيس

عدد أدوات التأريض

الحقول

count عدد صحيح  (اختياري)

عدد أدوات التأريض.

type enum (string)  (اختياري)

نوع أداة التأسيس المرتبطة بالعدد

القيم المحتملة:

  • google_search

    تحديد المصدر من خلال "بحث Google" و"بحث الصور"، وتحديد المصدر من الويب للشركات

  • google_maps

    استخدام "خرائط Google" كمصدر

input_tokens_by_modality array (ModalityTokens)  (اختيارية)

تقسيم استخدام الرموز المميزة للإدخال حسب طريقة الإدخال

عدد الرموز المميزة الخاصة بنوع ردّ واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميزة للوسائط

output_tokens_by_modality array (ModalityTokens)  (اختيارية)

تفاصيل استخدام الرموز المميزة للناتج حسب نوع البيانات

عدد الرموز المميزة لنمط استجابة واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميزة للوسيط

tool_use_tokens_by_modality array (ModalityTokens)  (اختياري)

تفصيل لاستخدام الرموز المميزة الخاصة باستخدام الأدوات حسب نوع البيانات

عدد الرموز المميزة الخاصة بنوع ردّ واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميزة للوسيط

total_cached_tokens integer  (اختيارية)

عدد الرموز المميّزة في الجزء المخزّن مؤقتًا من الطلب (المحتوى المخزّن مؤقتًا)

total_input_tokens integer  (اختيارية)

عدد الرموز المميزة في الطلب (السياق).

total_output_tokens عدد صحيح  (اختيارية)

إجمالي عدد الرموز المميزة في جميع الردود التي تم إنشاؤها

total_thought_tokens integer  (اختيارية)

عدد الرموز المميّزة للأفكار في نماذج التفكير

total_tokens integer  (optional)

إجمالي عدد الرموز المميّزة لطلب التفاعل (الطلب + الردود + الرموز المميّزة الداخلية الأخرى).

total_tool_use_tokens عدد صحيح  (اختياري)

عدد الرموز المميزة المتوفّرة في طلبات استخدام الأدوات

مثال

مثال على الردّ

{
  "accent": "string",
  "context": "string",
  "description": "string",
  "display_name": "string",
  "expire_time": "string",
  "gender": "string",
  "id": "string",
  "key": "string",
  "language_code": "string",
  "model": "string",
  "persona": "string",
  "pitch": "low",
  "prompted": {
    "input": "string"
  },
  "region_code": "string",
  "replicated": {
    "consent_audio": {
      "data": "string",
      "mime_type": "string"
    },
    "source_audio": {
      "data": "string",
      "mime_type": "string"
    }
  },
  "sample_audio": {
    "data": "string",
    "mime_type": "string"
  },
  "type": "replicated",
  "usage": {
    "cached_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "grounding_tool_count": [
      {
        "count": 0,
        "type": "google_search"
      }
    ],
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "output_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "tool_use_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 0,
    "total_output_tokens": 0,
    "total_thought_tokens": 0,
    "total_tokens": 0,
    "total_tool_use_tokens": 0
  }
}

DeleteVoice

delete https://generativelanguage.googleapis.com/v1beta/voices/{voicesId}

يحذف هذا الإجراء صوتًا مخصّصًا مخزَّنًا (`store = true`) حسب اسم المورد. لا يمكن حذف الأصوات المضمّنة في الكتالوج (`VOICE_TYPE_PREBUILT`).

مَعلمات المسار / طلب البحث

voicesId string  (مطلوبة)

الحقل مطلوب. اسم المورد الخاص بالصوت المخصّص المخزَّن المطلوب حذفه (على سبيل المثال، `voices/voice_abc123def456`)

الردّ

إذا كانت الاستجابة ناجحة، ستكون فارغة.

مثال

الموارد

الصوت

تمثّل هذه السمة مصدر صوت إما صوتًا مخصّصًا (تم إنشاؤه من خلال `CreateVoice`) أو صوتًا مسبق الإنشاء (يتم عرضه من خلال `ListVoices`).

الحقول

accent string  (اختياري)

اختيارية: واصف اللهجة الإقليمية (مثلاً "أمريكية" أو "بريطانية")

context string  (اختياري)

اختيارية: سياق الاستخدام أو النطاق الأمثل (مثل "محادثة" أو "كتاب مسموع" أو "أخبار")

الوصف string  (اختياري)

اختيارية: ملخّص وصفي لنبرة الصوت والشخصية والأسلوب

display_name string  (اختياري)

اختيارية: اسم العرض المقدَّم من المستخدم لصوت مخزَّن (`store = true`)، أو اسم الكتالوج لصوت مُعدّ مسبقًا

expire_time string  (اختياري)

النتائج فقط. الطابع الزمني الذي تنتهي فيه صلاحية الصوت المخصّص المخزّن (`store = true`) أو مفتاح الصوت المنسوخ (`store = false`). يتم ضبط القيمة على "غير مضبوط" لأصوات الكتالوجات المسبقة الإنشاء (`"prebuilt"`) التي لا تنتهي صلاحيتها.

gender string  (اختياري)

اختيارية: عرض الجنس المتصوّر للصوت (مثلاً "أنثى" أو "ذكر" أو "محايد").

id string  (اختياري)

النتائج فقط. المعرّف الفريد للصوت * بالنسبة إلى الأصوات المخصّصة التي تديرها Google‏ (`store = true`)، يكون هذا المعرّف من إنشاء النظام ويبدأ بالبادئة `voice_` (مثلاً، `voice_abc123def456`). مرِّر `voices/{id}` كـ `name` في `GetVoice` و `DeleteVoice`، ومرِّر `{id}` مباشرةً إلى `SpeechConfig.voice_config.voice` (أو `SpeechConfig.voice`) أثناء تركيب الكلام. * بالنسبة إلى الأصوات المضمّنة في الكتالوج (`"prebuilt"` التي تعرضها الدالة `ListVoices`)، هذا هو اسم المتحدث (على سبيل المثال، `Puck` أو `Charon`). * يتم ضبط القيمة على "غير محدّد" عند استدعاء الدالة `CreateVoice` مع ضبط `store = false`.

key string  (اختياري)

النتائج فقط. مفتاح تكرار الصوت الذي يديره العميل (مع البادئة `voicekey_`). يتم عرضه فقط من خلال `CreateVoice` عندما يكون `type` هو `"replicated"` و `store` هو `false`. مرِّر هذا المفتاح إلى `SpeechConfig.voice_config.voice` (أو `SpeechConfig.voice`) أثناء تركيب الكلام.

language_code سلسلة  (اختيارية)

اختيارية: علامة اللغة الأساسية وفق المعيار BCP-47 (مثل "en-US" أو "fr-FR").

model string  (اختياري)

اختيارية: النموذج المستخدَم لتصميم الصوت أو تكراره في حال عدم تضمينها في `CreateVoice`، سيتم تلقائيًا استخدام أحدث نموذج متوافق لتصميم الصوت. يتم عرض هذه السمة في ردود `CreateVoice` و`GetVoice` و `ListVoices` للأصوات المخصّصة (`"prompted"` و `"replicated"`)، ويتم ضبطها على "غير محدّد" للأصوات `"prebuilt"`. يمكن تركيب الأصوات التي تم إنشاؤها باستخدام أي نموذج تركيب متوافق مع ميزة تحويل النص إلى كلام.

persona string  (اختياري)

اختيارية: الشخصية المقصودة أو النموذج الأصلي للشخصية (مثل "ودود ولطيف" أو "راوٍ").

pitch Pitch  (اختياري)

اختيارية: تصنيف درجة الصوت

القيم المحتملة

  • low

    نبرة صوت منخفضة

  • medium

    صوت متوسط الحدة

  • high

    نبرة صوت عالية

تمت المطالبة PromptedVoice  (اختياري)

مَعلمات لإنشاء الصوت بناءً على طلب مطلوبة في `CreateVoice` عندما تكون قيمة `type` هي `"prompted"`. يتم عرضها في الردود على طلبات `CreateVoice` و`GetVoice` و `ListVoices` للأصوات التي تم إنشاؤها بناءً على طلب.

مَعلمات لإنشاء الصوت بناءً على طلب مطلوبة في `CreateVoice` عندما تكون قيمة `type` هي `"prompted"`. يتم عرضها في ردود `CreateVoice` و`GetVoice` و `ListVoices` للأصوات التي تم إنشاؤها بناءً على طلب.

الحقول

input string  (اختياري)

الحقل مطلوب. طلب باللغة الطبيعية يصف الصوت المطلوب، مثل "صوت رجالي عميق وقوي لغول شرير ضخم في منتصف العمر"

region_code string  (اختيارية)

اختيارية: رمز المنطقة الجغرافية وفقًا لمعيار ISO 3166-1 alpha-2 أو معيار الأمم المتحدة M.49 (مثل "US" أو "GB" أو "001")

sample_audio AudioData  (اختياري)

النتائج فقط. محتوى صوتي تجريبي (محتوى صوتي من طلب باستخدام آلة المزج) تم إنشاؤه لصوت مطلوب يتم ملء هذا الحقل فقط في ردود `CreateVoice` و`GetVoice` عندما تكون قيمة `type` هي `"prompted"`، ويتم إلغاء ضبطه في ردود `ListVoices` وفي حال كانت قيمة `type` هي `"replicated"` أو `"prebuilt"`.

حمولة الصوت المستخدَمة لإنشاء الصوت

الحقول

data string  (اختياري)

الحقل مطلوب. وحدات البايت الخاصة بالصوت الخام

mime_type string  (اختيارية)

الحقل مطلوب. نوع MIME الخاص ببيانات الصوت وفقًا لهيئة IANA (على سبيل المثال، `audio/wav` أو `audio/mpeg`).

type VoiceType  (اختياري)

الحقل مطلوب. تمثّل هذه السمة نوع الصوت. في `CreateVoice`، يجب أن تكون القيمة `"replicated"` أو `"prompted"`. في ردود `ListVoices`، يمكن أن تكون القيمة أيضًا `"prebuilt"`.

القيم المحتملة

  • replicated

    صوت مخصّص تم إنشاؤه من عيّنة صوتية مرجعية وتسجيل موافقة المتحدث

  • prompted

    صوت مخصّص تم إنشاؤه من طلب نصي باللغة الطبيعية

  • prebuilt

    صوت نظام مضمّن من كتالوج الأصوات من Google (مثل `Puck` أو `Charon`)، يتم عرضه في الردود، ولا يمكن تحديده كنوع في `CreateVoice`.

usage Usage  (اختياري)

النتائج فقط. إحصاءات استخدام الرموز المميزة لطلب إنشاء الصوت يتم ملء هذا الحقل فقط في ردّ `CreateVoice` عندما يكون `type` هو `"prompted"`، ويكون غير مضبوط في `"replicated"` وفي ردود `GetVoice` و `ListVoices`.

إحصاءات حول استخدام الرمز المميّز لطلب التفاعل.

الحقول

cached_tokens_by_modality array (ModalityTokens)  (اختياري)

تفاصيل استخدام الرموز المميزة المخزّنة مؤقتًا حسب طريقة العرض

عدد الرموز المميزة الخاصة بنوع ردّ واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميّزة للوسيط

grounding_tool_count array (GroundingToolCount)  (اختياري)

عدد أدوات التأسيس

عدد أدوات التأريض

الحقول

count عدد صحيح  (اختياري)

عدد أدوات التأريض.

type enum (string)  (اختياري)

نوع أداة التأسيس المرتبطة بالعدد

القيم المحتملة:

  • google_search

    تحديد المصدر من خلال "بحث Google" و"بحث الصور"، وتحديد المصدر من الويب للشركات

  • google_maps

    استخدام "خرائط Google" كمصدر

input_tokens_by_modality array (ModalityTokens)  (اختيارية)

تقسيم استخدام الرموز المميزة للإدخال حسب طريقة الإدخال

عدد الرموز المميزة الخاصة بنوع ردّ واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميزة للوسائط

output_tokens_by_modality array (ModalityTokens)  (اختيارية)

تفاصيل استخدام الرموز المميزة للناتج حسب نوع البيانات

عدد الرموز المميزة لنمط استجابة واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميزة للوسيط

tool_use_tokens_by_modality array (ModalityTokens)  (اختياري)

تفصيل لاستخدام الرموز المميزة الخاصة باستخدام الأدوات حسب نوع البيانات

عدد الرموز المميزة الخاصة بنوع ردّ واحد

الحقول

modality ResponseModality  (اختياري)

الوسيط المرتبط بعدد الرموز المميزة

القيم المحتملة

  • text

    تشير إلى أنّ النموذج يجب أن يعرض نصًا.

  • image

    تشير إلى أنّ النموذج يجب أن يعرض صورًا.

  • audio

    تشير إلى أنّ النموذج يجب أن يعرض صوتًا.

  • video

    تشير إلى أنّ النموذج يجب أن يعرض فيديو.

  • document

    تشير إلى أنّ النموذج يجب أن يعرض المستندات.

tokens عدد صحيح  (اختياري)

عدد الرموز المميزة للوسيط

total_cached_tokens integer  (اختيارية)

عدد الرموز المميّزة في الجزء المخزّن مؤقتًا من الطلب (المحتوى المخزّن مؤقتًا)

total_input_tokens integer  (اختيارية)

عدد الرموز المميزة في الطلب (السياق).

total_output_tokens عدد صحيح  (اختيارية)

إجمالي عدد الرموز المميزة في جميع الردود التي تم إنشاؤها

total_thought_tokens integer  (اختيارية)

عدد الرموز المميّزة للأفكار في نماذج التفكير

total_tokens integer  (optional)

إجمالي عدد الرموز المميّزة لطلب التفاعل (الطلب + الردود + الرموز المميّزة الداخلية الأخرى).

total_tool_use_tokens عدد صحيح  (اختياري)

عدد الرموز المميزة المتوفّرة في طلبات استخدام الأدوات