فهم الصوت

يمكن لـ Gemini تحليل وفهم الإدخال الصوتي، ما يتيح حالات استخدام مثل ما يلي:

  • وصف المحتوى الصوتي أو تلخيصه أو الإجابة عن أسئلة حوله
  • قدِّم نصًا للمحتوى الصوتي.
  • تحليل مقاطع معيّنة من الصوت

يوضّح لك هذا الدليل كيفية استخدام Gemini API لإنشاء رد نصي على إدخال صوتي.

قبل البدء

قبل استدعاء Gemini API، تأكَّد من تثبيت حزمة تطوير البرامج (SDK) التي تختارها وإعداد مفتاح Gemini API وجاهزيته للاستخدام.

إدخال الصوت

يمكنك تقديم بيانات صوتية إلى Gemini بالطرق التالية:

تحميل ملف صوتي

يمكنك استخدام Files API لتحميل ملف صوتي. استخدِم دائمًا Files API عندما يتجاوز إجمالي حجم الطلب (بما في ذلك الملفات، والنص المطلوب، وتعليمات النظام، وما إلى ذلك) 20 ميغابايت.

يحمّل الرمز التالي ملفًا صوتيًا ثم يستخدمه في طلب إلى generateContent.

Python

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-2.5-flash", contents=["Describe this audio clip", myfile]
)

print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/sample.mp3",
    config: { mimeType: "audio/mp3" },
  });

  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: createUserContent([
      createPartFromUri(myfile.uri, myfile.mimeType),
      "Describe this audio clip",
    ]),
  });
  console.log(response.text);
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

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

  localAudioPath := "/path/to/sample.mp3"
  uploadedFile, _ := client.Files.UploadFromPath(
      ctx,
      localAudioPath,
      nil,
  )

  parts := []*genai.Part{
      genai.NewPartFromText("Describe this audio clip"),
      genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
  }
  contents := []*genai.Content{
      genai.NewContentFromParts(parts, genai.RoleUser),
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-2.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

AUDIO_PATH="path/to/sample.mp3"
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Describe this audio clip"},
          {"file_data":{"mime_type": "${MIME_TYPE}", "file_uri": '$file_uri'}}]
        }]
      }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

لمزيد من المعلومات حول العمل باستخدام ملفات الوسائط، يُرجى الاطّلاع على Files API.

تمرير بيانات الصوت مضمّنة

بدلاً من تحميل ملف صوتي، يمكنك تمرير بيانات صوتية مضمّنة في الطلب إلى generateContent:

Python

from google.genai import types

with open('path/to/small-sample.mp3', 'rb') as f:
    audio_bytes = f.read()

response = client.models.generate_content(
  model='gemini-2.5-flash',
  contents=[
    'Describe this audio clip',
    types.Part.from_bytes(
      data=audio_bytes,
      mime_type='audio/mp3',
    )
  ]
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});
const base64AudioFile = fs.readFileSync("path/to/small-sample.mp3", {
  encoding: "base64",
});

const contents = [
  { text: "Please summarize the audio." },
  {
    inlineData: {
      mimeType: "audio/mp3",
      data: base64AudioFile,
    },
  },
];

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: contents,
});
console.log(response.text);

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

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

  audioBytes, _ := os.ReadFile("/path/to/small-sample.mp3")

  parts := []*genai.Part{
      genai.NewPartFromText("Describe this audio clip"),
    &genai.Part{
      InlineData: &genai.Blob{
        MIMEType: "audio/mp3",
        Data:     audioBytes,
      },
    },
  }
  contents := []*genai.Content{
      genai.NewContentFromParts(parts, genai.RoleUser),
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-2.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

في ما يلي بعض النقاط التي يجب أخذها في الاعتبار بشأن بيانات الصوت المضمّنة:

  • يبلغ الحد الأقصى لحجم الطلب 20 ميغابايت، ويشمل ذلك الطلبات النصية وتعليمات النظام والملفات المقدَّمة بشكل مضمّن. إذا كان حجم ملفك سيؤدي إلى تجاوز إجمالي حجم الطلب 20 ميغابايت، استخدِم Files API لتحميل ملف صوتي لاستخدامه في الطلب.
  • إذا كنت تستخدم عيّنة صوتية عدة مرات، من الأفضل تحميل ملف صوتي.

الحصول على نص

للحصول على نص لبيانات صوتية، ما عليك سوى طلب ذلك في الطلب:

Python

myfile = client.files.upload(file='path/to/sample.mp3')
prompt = 'Generate a transcript of the speech.'

response = client.models.generate_content(
  model='gemini-2.5-flash',
  contents=[prompt, myfile]
)

print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({});
const myfile = await ai.files.upload({
  file: "path/to/sample.mp3",
  config: { mimeType: "audio/mpeg" },
});

const result = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
    "Generate a transcript of the speech.",
  ]),
});
console.log("result.text=", result.text);

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

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

  localAudioPath := "/path/to/sample.mp3"
  uploadedFile, _ := client.Files.UploadFromPath(
      ctx,
      localAudioPath,
      nil,
  )

  parts := []*genai.Part{
      genai.NewPartFromText("Generate a transcript of the speech."),
      genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
  }
  contents := []*genai.Content{
      genai.NewContentFromParts(parts, genai.RoleUser),
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-2.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

الرجوع إلى الطوابع الزمنية

يمكنك الإشارة إلى أقسام معيّنة من ملف صوتي باستخدام طوابع زمنية بالتنسيق MM:SS. على سبيل المثال، يطلب الطلب التالي نسخة مكتوبة

  • يبدأ عند الدقيقة 2 و30 ثانية من بداية الملف.
  • ينتهي عند 3 دقائق و29 ثانية من بداية الملف.

Python

# Create a prompt containing timestamps.
prompt = "Provide a transcript of the speech from 02:30 to 03:29."

JavaScript

// Create a prompt containing timestamps.
const prompt = "Provide a transcript of the speech from 02:30 to 03:29."

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

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

  localAudioPath := "/path/to/sample.mp3"
  uploadedFile, _ := client.Files.UploadFromPath(
      ctx,
      localAudioPath,
      nil,
  )

  parts := []*genai.Part{
      genai.NewPartFromText("Provide a transcript of the speech " +
                            "between the timestamps 02:30 and 03:29."),
      genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
  }
  contents := []*genai.Content{
      genai.NewContentFromParts(parts, genai.RoleUser),
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-2.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

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

استدعِ طريقة countTokens للحصول على عدد الرموز المميزة في ملف صوتي. على سبيل المثال:

Python

response = client.models.count_tokens(
  model='gemini-2.5-flash',
  contents=[myfile]
)

print(response)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({});
const myfile = await ai.files.upload({
  file: "path/to/sample.mp3",
  config: { mimeType: "audio/mpeg" },
});

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.5-flash",
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
  ]),
});
console.log(countTokensResponse.totalTokens);

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

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

  localAudioPath := "/path/to/sample.mp3"
  uploadedFile, _ := client.Files.UploadFromPath(
      ctx,
      localAudioPath,
      nil,
  )

  parts := []*genai.Part{
      genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
  }
  contents := []*genai.Content{
      genai.NewContentFromParts(parts, genai.RoleUser),
  }

  tokens, _ := client.Models.CountTokens(
      ctx,
      "gemini-2.5-flash",
      contents,
      nil,
  )

  fmt.Printf("File %s is %d tokens\n", localAudioPath, tokens.TotalTokens)
}

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

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

  • WAV - audio/wav
  • MP3 - audio/mp3
  • AIFF - audio/aiff
  • AAC - audio/aac
  • OGG Vorbis - audio/ogg
  • FLAC - audio/flac

التفاصيل الفنية حول الصوت

  • يمثّل Gemini كل ثانية من الصوت بـ 32 رمزًا مميزًا. على سبيل المثال، يتم تمثيل دقيقة واحدة من الصوت بـ 1,920 رمزًا مميزًا.
  • يمكن أن "يفهم" Gemini المكوّنات غير الكلامية، مثل تغريد الطيور أو صفارات الإنذار.
  • الحد الأقصى لطول البيانات الصوتية المسموح به في طلب واحد هو 9.5 ساعات. لا يفرض Gemini أي قيود على عدد الملفات الصوتية في الطلب الواحد، ولكن يجب ألا يتجاوز إجمالي المدة المجمّعة لجميع الملفات الصوتية في الطلب الواحد 9.5 ساعات.
  • يقلّل Gemini من دقة ملفات الصوت إلى 16 كيلوبت في الثانية.
  • إذا كان مصدر الصوت يتضمّن قنوات متعددة، يدمج Gemini هذه القنوات في قناة واحدة.

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

يوضّح هذا الدليل كيفية إنشاء نص استجابةً لبيانات صوتية. لمزيد من المعلومات، يُرجى الاطّلاع على المراجع التالية:

  • استراتيجيات طلب الملفات: تتيح Gemini API إمكانية طلب الملفات باستخدام بيانات نصية وصور وصوت وفيديو، ويُعرف ذلك أيضًا باسم طلبات البحث المتعددة الوسائط.
  • تعليمات النظام: تتيح لك تعليمات النظام توجيه سلوك النموذج استنادًا إلى احتياجاتك وحالات الاستخدام المحدّدة.
  • إرشادات الأمان: في بعض الأحيان، تنتج نماذج الذكاء الاصطناعي التوليدي نتائج غير متوقعة، مثل نتائج غير دقيقة أو متحيزة أو مسيئة. تُعد المعالجة اللاحقة والتقييم البشري أساسيَّين للحدّ من خطر الأضرار الناجمة عن هذه النتائج.