أصبحت Interactions API متاحة الآن للجميع. ننصحك باستخدام واجهة برمجة التطبيقات هذه للوصول إلى جميع أحدث الميزات والنماذج.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

تحويل الصوت إلى نص

تحوّل Gemini API الكلام في الملفات الصوتية إلى نص باستخدام نموذج Gemini 3.5 Transcribe (gemini-3.5-transcribe). واستنادًا إلى إمكانات Gemini في فهم الصوت، يقدّم خدمة تحويل الصوت إلى نص بدقة مع التعرّف التلقائي على اللغة، وتحديد المتحدثين، والطوابع الزمنية على مستوى الكلمات، وتلميحات المفردات المخصّصة. يتضمّن أيضًا وضع النسخ الذكي الذي يزيل العثرات في الكلام ويوفّر تنسيقًا ذكيًا.

لتحويل ملف صوتي إلى نص، حمِّل الملف الصوتي وأرسِله إلى gemini-3.5-transcribe:

Python

from google import genai

client = genai.Client()

audio_file = client.files.upload(file="path/to/sample.mp3")

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
)

print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

const audioFile = await client.files.upload({
  file: "path/to/sample.mp3",
  config: { mime_type: "audio/mp3" },
});

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
});

console.log(interaction.output_text);

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

REST

# First upload the file via the Files API, then pass its URI:
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.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ]
  }'

نظرة عامة

تم تحسين Gemini 3.5 Transcribe لمهام تحويل الكلام إلى نص. تتعامل هذه الميزة مع اللهجات المختلفة والضوضاء في الخلفية والمحادثات المتعددة اللغات.

تشمل الإمكانات الرئيسية ما يلي:

التعرّف التلقائي على الكلام (ASR): يرصد اللغات تلقائيًا في أكثر من 85 لغة. يتعامل مع تبديل اللغة داخل الجملة وبين الجمل بدون إعداد يدوي.
المفردات المخصّصة: يتم تحسين التعرّف على المصطلحات والاختصارات والأسماء الخاصة بالنطاق من خلال إدخال ما يصل إلى 1,000 عبارة.
تحديد المتحدّثين: يميز بين المتحدّثين المتعددين وينسب المقاطع المنطوقة إلى تصنيفات مختلفة.
الطوابع الزمنية على مستوى الكلمات: يتم إنشاء إزاحات دقيقة لوقتَي البدء والانتهاء لكل كلمة تم التعرّف عليها.
تحويل الصوت إلى نص بذكاء: تنقّح النص من أخطاء الكلام وكلمات الحشو والتكرار، وتطبّق تنسيقًا منظَّمًا.
التنسيق والتسوية: يتم تطبيق الكتابة بالأحرف اللاتينية الكبيرة وعلامات الترقيم وتسوية النص العكسي، مثل تحويل "ستة وعشرون مليون دولار أمريكي" إلى "26 مليون دولار أمريكي".

لفهم المحتوى الصوتي بشكل عام أو الإجابة عن الأسئلة حوله، استخدِم فهم المحتوى الصوتي. لتركيب الصوت من النص، استخدِم تحويل النص إلى كلام.

اقتراحات واكتشاف اللغة

يتعرّف النموذج تلقائيًا على اللغة المنطوقة. ويبدّل بين اللغات بشكل ديناميكي عندما يغيّر المتحدثون اللغة التي يتحدثون بها.

لاستخدام ميزة "التعرّف التلقائي"، احذف language_codes أو قدِّم قائمة فارغة:

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "language_codes": [],
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      language_codes: [],
    },
  },
});

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    LanguageCodes: []string{},
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "language_codes": []
      }
    }
  }'

إذا كنت تعرف اللغة مسبقًا، حدِّد رموز اللغة BCP-47 في language_codes لتحسين دقة النسخ (راجِع اللغات المتوافقة):

Python

generation_config = {
    "transcription_config": {
        "language_codes": ["es-ES"],
    }
}

JavaScript

const generationConfig = {
  transcription_config: {
    language_codes: ["es-ES"],
  },
};

Go

package main

import (
    "google.golang.org/genai/interactions/models/interactions"
)

func main() {
    generationConfig := &interactions.GenerationConfig{
        TranscriptionConfig: &interactions.TranscriptionConfig{
            LanguageCodes: []string{"es-ES"},
        },
    }
    _ = generationConfig
}

REST

{
  "generation_config": {
    "transcription_config": {
      "language_codes": ["es-ES"]
    }
  }
}

المفردات المخصّصة

يمكنك توجيه نموذج الكلام نحو الكلمات غير الشائعة أو المصطلحات الفنية أو أسماء العلامات التجارية أو أسماء العَلم. قدِّم ما يصل إلى 1,000 عبارة في مصفوفة custom_vocabulary (عادةً ما يتم تحقيق أفضل النتائج باستخدام ما يصل إلى 100 عبارة):

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"],
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      custom_vocabulary: ["Gemini", "Kubernetes", "BigQuery"],
    },
  },
});

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    CustomVocabulary: []string{"Gemini", "Kubernetes", "BigQuery"},
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"]
      }
    }
  }'

تمييز أصوات المتحدّثِين

تحدّد ميزة "تحديد هوية المتحدّث" الأصوات المختلفة في التسجيل وتضع علامة على كل مقطع باستخدام معرّف المتحدّث، مثل spk_1 أو spk_2. يمكن إضافة ما يصل إلى 8 متحدثين (تحديد هوية 3 متحدثين أو أكثر هو ميزة تجريبية).

فعِّل ميزة "تمييز أصوات المتحدّثِين" من خلال ضبط diarization_mode ضمن mode:

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "mode": {
                "type": "verbatim",
                "diarization_mode": "speaker",
            },
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      mode: {
        type: "verbatim",
        diarization_mode: "speaker",
      },
    },
  },
});

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                        DiarizationMode: genai.Ptr("speaker"),
                    }))),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": {
          "type": "verbatim",
          "diarization_mode": "speaker"
        }
      }
    }
  }'

الطوابع الزمنية على مستوى الكلمات

توفّر الطوابع الزمنية على مستوى الكلمات إزاحات دقيقة للبدء والانتهاء لكل كلمة يتم التعرّف عليها في بث الصوت.

فعِّل الطوابع الزمنية من خلال ضبط timestamp_granularities ضمن mode:

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "mode": {
                "type": "verbatim",
                "timestamp_granularities": ["word"],
            },
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      mode: {
        type: "verbatim",
        timestamp_granularities: ["word"],
      },
    },
  },
});

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                        TimestampGranularities: []string{"word"},
                    }))),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": {
          "type": "verbatim",
          "timestamp_granularities": ["word"]
        }
      }
    }
  }'

يمكنك الجمع بين diarization_mode وtimestamp_granularities في mode لتلقّي تصنيفات المتحدّثين والطوابع الزمنية للكلمات:

Python

generation_config = {
    "transcription_config": {
        "mode": {
            "type": "verbatim",
            "diarization_mode": "speaker",
            "timestamp_granularities": ["word"],
        },
    }
}

JavaScript

const generationConfig = {
  transcription_config: {
    mode: {
      type: "verbatim",
      diarization_mode: "speaker",
      timestamp_granularities: ["word"],
    },
  },
};

Go

package main

import (
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
)

func main() {
    generationConfig := &interactions.GenerationConfig{
        TranscriptionConfig: &interactions.TranscriptionConfig{
            Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                DiarizationMode:        genai.Ptr("speaker"),
                TimestampGranularities: []string{"word"},
            }))),
        },
    }
    _ = generationConfig
}

REST

{
  "generation_config": {
    "transcription_config": {
      "mode": {
        "type": "verbatim",
        "diarization_mode": "speaker",
        "timestamp_granularities": ["word"]
      }
    }
  }
}

أوضاع تحويل الصوت إلى نص

تتيح أداة Gemini 3.5 Transcribe وضعَين لتحويل الصوت إلى نص من خلال المَعلمة mode:

verbatim (الإعداد التلقائي): تعرض هذه السمة نصًا مطابقًا تمامًا لكل ما يُقال، مع الحفاظ على الكلمات الحشو الخام ("أمم" و"آه" و"يعني" و"كما تعلم") والتكرار والتوقفات والبدايات الخاطئة. يتم ضبط الطوابع الزمنية وميزة "تمييز أصوات المتحدّثِين" في هذا الوضع ({"type": "verbatim", ...}).
smart (النسخ الذكي): تحسين النص المكتوب ليكون قابلاً للقراءة من خلال تطبيق معالجة ذكية بعد التسجيل:
- إزالة أخطاء التلعثم: تزيل هذه الميزة كلمات الحشو في المحادثات والتلعثم وبدايات الجمل الخاطئة.
- التصحيحات الذاتية المضمّنة: تحلّ التصحيحات المنطوقة مباشرةً (على سبيل المثال، تتحوّل الجملة "لنجتمع يوم الثلاثاء، لا بل يوم الأربعاء في الساعة الثانية" إلى "لنجتمع يوم الأربعاء في الساعة 2:00 ظهرًا").
- التنسيق المنظَّم التلقائي: ينظّم الأفكار المنطوقة تلقائيًا في فقرات وقوائم مرقّمة ونقاط تعداد وتواريخ وعملات وأرقام منسَّقة.
- التصحيح النحوي: يضيف علامات الترقيم المناسبة ويعدّل حالة الأحرف في الجملة ويحسّن من سلاسة النص.

محتوى كلامي صوتي	`verbatim` الناتج	ناتج `smart` (التحويل الذكي للصوت إلى نص)
"حسنًا، بالنسبة إلى الاجتماع، أعتقد أنّه علينا دعوة "منى"، لا، "عماد" و"كارول".	"حسنًا، بالنسبة إلى الاجتماع، أعتقد أنّه علينا دعوة نبيلة، لا بل يوسف وكارول".	"أعتقد أنّه علينا دعوة "بوب" و"كارول" لحضور الاجتماع".
مراجعة العنصر الأول للميزانية، تحديد الجدول الزمني للعنصر الثاني، إرسال ملخّص للعنصر الثالث	"first item review budget second item finalize timeline third item send recap"	"1- مراجعة الميزانية 2. وضع اللمسات الأخيرة على المخطّط الزمني 3. إرسال الملخّص"

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "mode": "smart",
        }
    },
)
print(interaction.output_text)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      mode: "smart",
    },
  },
});
console.log(interaction.output_text);

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.TranscriptionConfigModeEnumSmart)),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": "smart"
      }
    }
  }'

تحليل نتيجة تحويل الصوت إلى نص

يتم عرض نص المحادثة الكامل في interaction.output_text.

عند تفعيل timestamp_granularities أو diarization_mode، تعرض واجهة برمجة التطبيقات أيضًا تعليقات توضيحية مفصّلة على مستوى الكلمات مرفقة بمحتوى التفاعل.

في ما يلي كيفية استخراج الطوابع الزمنية للكلمات ونوبات التحدّث وتكرارها:

Python

def extract_word_annotations(interaction):
    words = []
    for step in getattr(interaction, "steps", []) or []:
        for content in getattr(step, "content", []) or []:
            for annotation in getattr(content, "annotations", []) or []:
                if getattr(annotation, "type", None) == "word_info":
                    words.append(annotation)
    return words

words = extract_word_annotations(interaction)

for w in words:
    speaker = f"[{w.speaker}] " if getattr(w, "speaker", None) else ""
    start = getattr(w, "start_offset", "")
    end = getattr(w, "end_offset", "")
    timing = f"({start} -> {end}) " if start and end else ""
    print(f"{speaker}{timing}{w.text}")

JavaScript

function extractWordAnnotations(interaction) {
  const words = [];
  for (const step of interaction.steps ?? []) {
    for (const content of step.content ?? []) {
      for (const annotation of content.annotations ?? []) {
        if (annotation.type === "word_info") {
          words.push(annotation);
        }
      }
    }
  }
  return words;
}

const words = extractWordAnnotations(interaction);

for (const w of words) {
  const speaker = w.speaker ? `[${w.speaker}] ` : "";
  const timing = (w.start_offset && w.end_offset) ? `(${w.start_offset} -> ${w.end_offset}) ` : "";
  console.log(`${speaker}${timing}${w.text}`);
}

Go

package main

import (
    "fmt"

    "google.golang.org/genai/interactions/models/interactions"
)

func extractWordAnnotations(interaction *interactions.Interaction) []*interactions.WordInfo {
    var words []*interactions.WordInfo
    if interaction == nil {
        return words
    }
    for _, step := range interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    for _, annotation := range content.TextContent.Annotations {
                        if annotation.WordInfo != nil {
                            words = append(words, annotation.WordInfo)
                        }
                    }
                }
            }
        }
    }
    return words
}

func main() {
    var interaction *interactions.Interaction
    words := extractWordAnnotations(interaction)

    for _, w := range words {
        speaker := ""
        if w.Speaker != nil && *w.Speaker != "" {
            speaker = fmt.Sprintf("[%s] ", *w.Speaker)
        }
        timing := ""
        if w.StartOffset != nil && w.EndOffset != nil {
            timing = fmt.Sprintf("(%s -> %s) ", *w.StartOffset, *w.EndOffset)
        }
        fmt.Printf("%s%s%s\n", speaker, timing, w.GetText())
    }
}

REST

{
  "id": "interactions/abc123xyz",
  "status": "completed",
  "steps": [
    {
      "id": "step_001",
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Hello world",
          "annotations": [
            {
              "type": "word_info",
              "text": "Hello",
              "speaker": "spk_1",
              "start_offset": "0.100s",
              "end_offset": "0.450s"
            },
            {
              "type": "word_info",
              "text": "world",
              "speaker": "spk_1",
              "start_offset": "0.500s",
              "end_offset": "0.850s"
            }
          ]
        }
      ]
    }
  ]
}

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

تتوفّر ميزة Gemini 3.5 Transcribe باللغات التالية ورموز اللغة BCP-47:

اللغة	رمز BCP-47	اللغة	رمز BCP-47
الأفريقانية	`af-ZA`	اليابانية	`ja-JP`
الأمهرية	`am-ET`	الجافانية	`jv-ID`
العربية (مصر)	`ar-EG`	كابوفيرديانو	`kea-CV`
الأرمينية	`hy-AM`	الكانادا	`kn-IN`
الأسامية	`as-IN`	الكازاخستانية	`kk-KZ`
أذربيجان	`az-AZ`	الكورية	`ko-KR`
البيلاروسية	`be-BY`	القيرغيزية	`ky-KG`
البنغالية (بنغلاديش)	`bn-BD`	اللاتفية	`lv-LV`
البنغالية (الهند)	`bn-IN`	اللينجالا	`ln-CD`
البوسنية	`bs-BA`	الليتوانية	`lt-LT`
البلغارية	`bg-BG`	المقدونية	`mk-MK`
البلغارية (الأرومانية)	`rup-BG`	الماليزية	`ms-MY`
البورمية	`my-MM`	المالايالامية	`ml-IN`
الكانتونية (التقليدية)	`yue-Hant-HK`	المالطية	`mt-MT`
الكتالانية	`ca-ES`	الصينية الماندرين (المبسطة)	`cmn-Hans-CN`
السيبيوانية	`ceb`	الماراثية	`mr-IN`
الخميرية القياسية	`km-KH`	المنغولية	`mn-MN`
الكرواتية	`hr-HR`	النيبالية	`ne-NP`
التشيكية	`cs-CZ`	النرويجية	`nb-NO`
الدانماركية	`da-DK`	الأوريا	`or-IN`
الهولندية	`nl-NL`	البولندية	`pl-PL`
الإنجليزية (بريطانيا العظمى)	`en-GB`	البرتغالية (البرازيل)	`pt-BR`
الإنجليزية (الهند)	`en-IN`	البرتغالية (البرتغال)	`pt-PT`
الإنجليزية (الولايات المتحدة)	`en-US`	البنجابية	`pa-IN`
الإستونية	`et-EE`	البنجابية (نص غورموخي)	`pa-Guru-IN`
الفارسية	`fa-IR`	الرومانية	`ro-RO`
الفلبينية	`fil-PH`	الروسية	`ru-RU`
الفنلندية	`fi-FI`	الصربية	`sr-RS`
الفرنسية	`fr-FR`	السندية (الخط العربي)	`sd-Arab-IN`
الغليشيانية	`gl-ES`	السلوفاكية	`sk-SK`
الجورجية	`ka-GE`	السلوفينية	`sl-SI`
الألمانية	`de-DE`	الإسبانية (أمريكا اللاتينية)	`es-419`
اليونانية	`el-GR`	الإسبانية (الولايات المتحدة)	`es-US`
الغوجاراتية	`gu-IN`	السواحيلية (كينيا)	`sw-KE`
الهوسا	`ha-NG`	السويدية	`sv-SE`
العبرية	`he-IL`	الطاجيكية	`tg-TJ`
الهندية	`hi-IN`	التيلوغوية	`te-IN`
الهنغارية	`hu-HU`	التايلاندية	`th-TH`
الأيسلندية	`is-IS`	التركية	`tr-TR`
الإنجليزية الهندية	`en-IN`	الأوكرانية	`uk-UA`
الإندونيسية	`id-ID`	الأوزبكية	`uz-UZ`
الإيطالية	`it-IT`	الفيتنامية	`vi-VN`

تنسيقات الصوت المتوافقة

يتوافق Gemini 3.5 Transcribe مع أنواع MIME التالية لتنسيقات الصوت:

WAV - audio/wav
MP3 - audio/mp3
AIFF - audio/aiff
AAC - audio/aac
OGG - audio/ogg
FLAC - audio/flac
MPEG - audio/mpeg
M4A - audio/m4a
L16 - audio/l16
‫Opus - ‏audio/opus
ALAW - audio/alaw
MULAW - audio/mulaw
WebM - audio/webm

للاطّلاع على القائمة الكاملة بأنواع MIME المتوافقة ومخططات المَعلمات، يُرجى الرجوع إلى مرجع Interactions API.

مرجع المَعلمة

اضبط عملية تحويل الصوت إلى نص من خلال ضبط الحقول ضِمن العنصر transcription_config في generation_config:

الحقل	النوع	الوصف
`language_codes`	مصفوفة سلاسل	رموز اللغة المستخدَمة وفق المعيار BCP-47 (مثل `["en-US"]`). في حال حذفها أو تركها فارغة (`[]`)، يرصد النموذج اللغة تلقائيًا ويتعامل مع تبديل الرموز.
`custom_vocabulary`	مصفوفة سلاسل	ما يصل إلى 1,000 مصطلح أو اختصار أو اسم علم مخصّص لتحسين دقة التعرّف على الكلام لا تتوافق هذه الميزة مع تحديد هوية المتحدثين والطوابع الزمنية على مستوى الكلمات.
`mode`	كائن أو سلسلة	إعدادات وضع تحويل الصوت إلى نص يقبل هذا الخيار القيمة `"smart"` أو عنصر وضع "النص كما هو" (`{"type": "verbatim", ...}`). القيمة التلقائية هي "النص كما هو".
`mode.type`	سلسلة	معرّف الوضع (في وضع "النص الحرفي" فقط) يجب ضبطها دائمًا على `"verbatim"`.
`mode.timestamp_granularities`	مصفوفة سلاسل	(وضع "مطابق تمامًا" فقط) دقة الطوابع الزمنية التي سيتم عرضها. مرِّر `["word"]` لتفعيل إزاحات بداية الكلمة ونهايتها. غير متوافق مع المفردات المخصّصة
`mode.diarization_mode`	سلسلة	(وضع "النص الحرفي فقط") وضع تحديد هوية المتحدث مرِّر `"speaker"` لتحديد المتحدّثين المميّزين وتصنيفهم. لا تتوافق مع المفردات المخصّصة.

أفضل الممارسات

توفير صوت واضح: تأكَّد من أنّ التسجيلات الصوتية تتضمّن فصلًا واضحًا للأصوات وتجنَّب التقطيع الشديد.
تقديم تلميحات حول اللغة عند معرفتها: إذا كنت تعرف لغة الصوت مسبقًا، حدِّد language_codes لتحقيق أقصى قدر من الدقة.
استهداف المفردات المخصّصة: لا تضمِّن في custom_vocabulary سوى عبارات مميّزة خاصة بالنطاق أو أسماء علامات تجارية أو أسماء علم، بدلاً من الكلمات الشائعة المستخدمة يوميًا.
استخدام Files API لتسجيلات صوتية كبيرة: بالنسبة إلى الملفات التي تزيد مدتها عن بضع ثوانٍ، حمِّل الملف باستخدام client.files.upload ومرِّر معرّف الموارد المنتظم (URI) للملف الذي تم إرجاعه إلى النموذج.

القيود

مدة الصوت: تتيح الطلبات الأحادية العادية استخدام ملفات صوتية تصل مدتها إلى ساعة واحدة. تقتصر معالجة الصوت على 30 دقيقة عند تفعيل ميزات مثل تحديد هوية المتحدث أو الطوابع الزمنية على مستوى الكلمات.
الطوابع الزمنية على مستوى الكلمات: قد يؤدي تفعيل الطوابع الزمنية على مستوى الكلمات إلى انخفاض دقة تحويل الصوت إلى نص بشكل عام.
تمييز أصوات المتحدّثِين: تتيح هذه الميزة التعرّف على ما يصل إلى 8 متحدثين. ميزة تحديد المتحدثين لثلاثة أشخاص أو أكثر هي ميزة تجريبية.
المفردات المخصّصة: يمكنك تقديم ما يصل إلى 1,000 عبارة في custom_vocabulary، ولكن عادةً ما يتم تحقيق أفضل النتائج باستخدام ما يصل إلى 100 عبارة. لا يمكنك الجمع بين custom_vocabulary وتحديد هوية المتحدث أو الطوابع الزمنية على مستوى الكلمات، وترفض واجهة برمجة التطبيقات الطلبات التي تحدّد custom_vocabulary إلى جانب أيّ من هاتين الميزتين.
التوافق مع الأوضاع: لا يمكن دمج ميزة "النسخ الذكي" ("smart") مع timestamp_granularities أو diarization_mode.

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

يمكنك بث الصوت في الوقت الفعلي باستخدام دليل تحويل الصوت إلى نص مباشرةً من خلال Live API.
استكشِف فهم الصوت لتحليل المحتوى الصوتي أو تلخيصه أو البحث فيه.
تعرَّف على كيفية إنشاء صوت من نص باستخدام ميزة تحويل النص إلى كلام.
راجِع صفحة الأسعار لمعرفة أسعار النماذج وحدود الرموز المميزة.
راجِع دليل Files API لمعرفة تفاصيل حول تحميل ملفات الوسائط وإدارتها.