הבנת אודיו

‫Gemini יכול לנתח ולהבין קלט אודיו, וכך לאפשר תרחישי שימוש כמו:

  • לתאר, לסכם או לענות על שאלות לגבי תוכן אודיו.
  • צריך לספק תמליל של האודיו.
  • לנתח פלחים ספציפיים של האודיו.

במדריך הזה מוסבר איך להשתמש ב-Gemini API כדי ליצור תשובת טקסט לקלט אודיו.

לפני שמתחילים

לפני שמפעילים את Gemini API, צריך לוודא שה-SDK שבחרתם מותקן, ומפתח Gemini API מוגדר ומוכן לשימוש.

קלט אודיו

יש כמה דרכים לספק ל-Gemini נתוני אודיו:

העלאה של קובץ אודיו

אפשר להשתמש ב-Files API כדי להעלות קובץ אודיו. תמיד צריך להשתמש ב-Files API כשגודל הבקשה הכולל (כולל הקבצים, הנחיית הטקסט, הוראות המערכת וכו') גדול מ-20 MB.

הקוד הבא מעלה קובץ אודיו ואז משתמש בקובץ בשיחה אל 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())
}

כמה דברים שחשוב לזכור לגבי נתוני אודיו מוטמעים:

  • הגודל המקסימלי של הבקשה הוא 20MB, כולל הנחיות טקסט, הוראות למערכת וקבצים שסופקו בשורה. אם גודל הקובץ יגרום לגודל הבקשה הכולל לחרוג מ-20MB, צריך להשתמש ב-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 מבצע דגימת חסר של קובצי אודיו לרזולוציית נתונים של 16Kbps.
  • אם מקור האודיו מכיל כמה ערוצים, Gemini משלב את הערוצים האלה לערוץ אחד.

המאמרים הבאים

במדריך הזה מוסבר איך ליצור טקסט בתגובה לנתוני אודיו. מידע נוסף זמין במשאבים הבאים:

  • אסטרטגיות להנחיות עם קבצים: Gemini API תומך בהנחיות עם נתוני טקסט, תמונה, אודיו ווידאו, שנקראות גם הנחיות מרובות מצבים.
  • הוראות למערכת: הוראות למערכת מאפשרות לכוון את התנהגות המודל בהתאם לצרכים הספציפיים ולתרחישי השימוש שלכם.
  • הנחיות בטיחות: לפעמים מודלים של AI גנרטיבי יוצרים תוצאות לא צפויות, כמו תוצאות לא מדויקות, מוטות או פוגעניות. עיבוד תמונה (Post Processing) והערכה אנושית חיוניים כדי לצמצם את הסיכון לנזק שעלול להיגרם מהתוצאות האלה.