Audioverständnis

Gemini kann Audioeingaben analysieren und verstehen. Das ermöglicht Anwendungsfälle wie die folgenden:

  • Audioinhalte beschreiben, zusammenfassen oder Fragen dazu beantworten
  • Geben Sie eine Transkription des Audioinhalts an.
  • Bestimmte Audiosegmente analysieren

In dieser Anleitung erfahren Sie, wie Sie mit der Gemini API eine Textantwort auf eine Audioeingabe generieren.

Hinweis

Bevor Sie die Gemini API aufrufen, müssen Sie das von Ihnen ausgewählte SDK installiert und einen Gemini API-Schlüssel konfiguriert und einsatzbereit haben.

Eingabeaudio

Sie können Audiodaten auf folgende Arten an Gemini senden:

Audiodatei hochladen

Sie können die Files API verwenden, um eine Audiodatei hochzuladen. Verwenden Sie immer die Files API, wenn die Gesamtgröße der Anfrage (einschließlich der Dateien, des Textprompts, der Systemanweisungen usw.) größer als 20 MB ist.

Im folgenden Code wird eine Audiodatei hochgeladen und dann in einem Aufruf von generateContent verwendet.

PythonJavaScriptOkREST
from google import genai

client = genai.Client(api_key="GOOGLE_API_KEY")

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

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

print(response.text)

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

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });

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.0-flash",
    contents: createUserContent([
      createPartFromUri(myfile.uri, myfile.mimeType),
      "Describe this audio clip",
    ]),
  });
  console.log(response.text);
}

await main();

file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
    log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
    genai.FileData{URI: file.URI},
    genai.Text("Describe this audio clip"))
if err != nil {
    log.Fatal(err)
}

printResponse(resp)

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?key=${GOOGLE_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.0-flash:generateContent?key=$GOOGLE_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

Weitere Informationen zur Arbeit mit Mediendateien findest du unter Files API.

Audiodaten inline übergeben

Anstatt eine Audiodatei hochzuladen, können Sie Inline-Audiodaten in der Anfrage an generateContent übergeben:

PythonJavaScriptOk
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.0-flash',
  contents=[
    'Describe this audio clip',
    types.Part.from_bytes(
      data=audio_bytes,
      mime_type='audio/mp3',
    )
  ]
)

print(response.text)

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

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
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.0-flash",
  contents: contents,
});
console.log(response.text);

// Initialize a Gemini model appropriate for your use case.
model := client.GenerativeModel("gemini-2.0-flash")

bytes, err := os.ReadFile("path/to/small-sample.mp3")
if err != nil {
  log.Fatal(err)
}

prompt := []genai.Part{
  genai.Blob{MIMEType: "audio/mp3", Data: bytes},
  genai.Text("Please summarize the audio."),
}

// Generate content using the prompt.
resp, err := model.GenerateContent(ctx, prompt...)
if err != nil {
  log.Fatal(err)
}

// Handle the response of generated text
for _, c := range resp.Candidates {
  if c.Content != nil {
    fmt.Println(*c.Content)
  }
}

Hinweise zu Inline-Audiodaten:

  • Die maximale Anfragegröße beträgt 20 MB. Dazu gehören Textprompts, Systemanweisungen und inline bereitgestellte Dateien. Wenn die Größe Ihrer Datei die Gesamtgröße der Anfrage auf über 20 MB ansteigen lässt, laden Sie mit der Files API eine Audiodatei hoch, die in der Anfrage verwendet werden soll.
  • Wenn Sie ein Audio-Sample mehrmals verwenden, ist es effizienter, eine Audiodatei hochzuladen.

Transkript abrufen

Wenn Sie ein Transkript von Audiodaten erhalten möchten, bitten Sie einfach im Prompt darum:

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

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

print(response.text)

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

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

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

// Initialize a Gemini model appropriate for your use case.
model := client.GenerativeModel("gemini-2.0-flash")

// Create a prompt using text and the URI reference for the uploaded file.
prompt := []genai.Part{
  genai.FileData{URI: sampleAudio.URI},
  genai.Text("Generate a transcript of the speech."),
}

// Generate content using the prompt.
resp, err := model.GenerateContent(ctx, prompt...)
if err != nil {
  log.Fatal(err)
}

// Handle the response of generated text
for _, c := range resp.Candidates {
  if c.Content != nil {
    fmt.Println(*c.Content)
  }
}

Zeitstempel verwenden

Mit Zeitstempeln vom Typ MM:SS kannst du auf bestimmte Abschnitte einer Audiodatei verweisen. Mit dem folgenden Prompt wird beispielsweise ein Transkript angefordert, das

  • Beginnt 2 Minuten und 30 Sekunden nach Beginn der Datei.

  • Endet 3 Minuten und 29 Sekunden nach Beginn der Datei.

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

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

// Create a prompt containing timestamps.
prompt := []genai.Part{
    genai.FileData{URI: sampleAudio.URI},
    genai.Text("Provide a transcript of the speech from 02:30 to 03:29."),
}

Tokens zählen

Rufen Sie die Methode countTokens auf, um die Anzahl der Tokens in einer Audiodatei zu erhalten. Beispiel:

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

print(response)

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

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

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

tokens, err := model.CountTokens(ctx, genai.FileData{URI: sampleAudio.URI})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("File %s is %d tokens", sampleAudio.DisplayName, tokens.TotalTokens)

Unterstützte Audioformate

Gemini unterstützt die folgenden MIME-Typen für Audioformate:

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

Technische Details zu Audioinhalten

  • Gemini stellt jede Audiosekunde als 32 Tokens dar. Eine Minute Audio entspricht beispielsweise 1.920 Tokens.
  • Gemini kann nur Antworten auf englischsprachige Sprache ableiten.
  • Gemini kann auch nicht-sprachbezogene Komponenten wie Vogelgezwitscher oder Sirenen „verstehen“.
  • Die maximal unterstützte Länge von Audiodaten in einem einzelnen Prompt beträgt 9,5 Stunden. In Gemini ist die Anzahl der Audiodateien in einem einzelnen Prompt nicht begrenzt.Die Gesamtlänge aller Audiodateien in einem einzelnen Prompt darf jedoch 9,5 Stunden nicht überschreiten.
  • Gemini reduziert Audiodateien auf eine Datenauflösung von 16 kbit/s.
  • Wenn die Audioquelle mehrere Kanäle enthält, werden diese von Gemini zu einem einzigen Kanal kombiniert.

Nächste Schritte

In diesem Leitfaden erfahren Sie, wie Sie Text als Reaktion auf Audiodaten generieren. Weitere Informationen finden Sie in den folgenden Ressourcen:

  • Strategien für Prompts aus Dateien: Die Gemini API unterstützt Prompts mit Text-, Bild-, Audio- und Videodaten, auch als multimodale Prompts bezeichnet.
  • Systemanweisungen: Mit Systemanweisungen können Sie das Verhalten des Modells entsprechend Ihren spezifischen Anforderungen und Anwendungsfällen steuern.
  • Sicherheitshinweise: Manchmal liefern Modelle für generative KI unerwartete Ergebnisse, z. B. ungenaue, voreingenommene oder anstößige Ergebnisse. Eine Nachbearbeitung und eine menschliche Bewertung sind unerlässlich, um das Risiko von Schäden durch solche Ausgaben zu begrenzen.