Compréhension audio

Gemini peut analyser et comprendre les entrées audio, ce qui permet les cas d'utilisation suivants:

  • décrire, résumer ou répondre à des questions sur un contenu audio ;
  • Fournissez une transcription de l'audio.
  • Analyser des segments spécifiques de l'audio

Ce guide vous explique comment utiliser l'API Gemini pour générer une réponse textuelle à une entrée audio.

Avant de commencer

Avant d'appeler l'API Gemini, assurez-vous d'avoir installé le SDK de votre choix et d'avoir configuré une clé API Gemini prête à l'emploi.

Audio d'entrée

Vous pouvez fournir des données audio à Gemini de différentes manières:

Importer un fichier audio

Vous pouvez utiliser l'API Files pour importer un fichier audio. Utilisez toujours l'API Files lorsque la taille totale de la requête (y compris les fichiers, l'invite de texte, les instructions système, etc.) est supérieure à 20 Mo.

Le code suivant importe un fichier audio, puis l'utilise dans un appel à generateContent.

PythonJavaScriptGoREST
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

Pour en savoir plus sur l'utilisation des fichiers multimédias, consultez la section API Files.

Transmettre des données audio intégrées

Au lieu d'importer un fichier audio, vous pouvez transmettre des données audio intégrées dans la requête à generateContent:

PythonJavaScriptGo
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)
  }
}

Quelques points à retenir concernant les données audio intégrées:

  • La taille maximale de la requête est de 20 Mo, ce qui inclut les requêtes textuelles, les instructions système et les fichiers fournis en ligne. Si la taille de votre fichier fait que la taille totale de la requête dépasse 20 Mo, utilisez l'API Files pour importer un fichier audio à utiliser dans la requête.
  • Si vous utilisez un extrait audio plusieurs fois, il est plus efficace d'importer un fichier audio.

Obtenir une transcription

Pour obtenir une transcription des données audio, il vous suffit de le demander dans l'invite:

PythonJavaScriptGo
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)
  }
}

Faire référence aux codes temporels

Vous pouvez faire référence à des sections spécifiques d'un fichier audio à l'aide d'horodatages au format MM:SS. Par exemple, l'invite suivante demande une transcription qui

  • Commence à 2 minutes et 30 secondes à partir du début du fichier.

  • Se termine à 3 minutes 29 secondes à partir du début du fichier.

PythonJavaScriptGo
# 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."),
}

Compter les jetons

Appelez la méthode countTokens pour obtenir le nombre de jetons dans un fichier audio. Exemple :

PythonJavaScriptGo
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)

Formats audio compatibles

Gemini est compatible avec les types MIME de formats audio suivants:

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

Détails techniques sur l'audio

  • Gemini représente chaque seconde d'audio par 32 jetons. Par exemple, une minute d'audio est représentée par 1 920 jetons.
  • Gemini ne peut inférer des réponses qu'à partir de la parole en anglais.
  • Gemini peut "comprendre" des composants non vocaux, comme le chant des oiseaux ou les sirènes.
  • La durée maximale acceptée pour les données audio d'une seule requête est de 9,5 heures. Gemini ne limite pas le nombre de fichiers audio dans une seule requête.Toutefois, la durée totale combinée de tous les fichiers audio d'une seule requête ne doit pas dépasser 9,5 heures.
  • Gemini réduit la résolution des fichiers audio à 16 kbit/s.
  • Si la source audio contient plusieurs canaux, Gemini les combine en un seul.

Étape suivante

Ce guide explique comment générer du texte en réponse à des données audio. Pour en savoir plus, consultez les ressources suivantes:

  • Stratégies d'invite de fichier: l'API Gemini prend en charge les invites avec des données textuelles, des images, des données audio et des données vidéo, également appelées invites multimodales.
  • Instructions système: les instructions système vous permettent d'orienter le comportement du modèle en fonction de vos besoins et de vos cas d'utilisation spécifiques.
  • Conseils de sécurité: Les modèles d'IA générative produisent parfois des résultats inattendus, comme des résultats inexacts, biaisés ou choquants. Le post-traitement et l'évaluation humaine sont essentiels pour limiter le risque de préjudices liés à ces sorties.