Comprensión de audio

Gemini puede analizar y comprender la entrada de audio, lo que permite casos de uso como los siguientes:

  • Describir, resumir o responder preguntas sobre el contenido de audio
  • Proporciona una transcripción del audio.
  • Analiza segmentos específicos del audio.

En esta guía, se muestra cómo usar la API de Gemini para generar una respuesta de texto a la entrada de audio.

Antes de comenzar

Antes de llamar a la API de Gemini, asegúrate de tener instalado el SDK que elijas y de que una clave de API de Gemini esté configurada y lista para usar.

Audio de entrada

Puedes proporcionar datos de audio a Gemini de las siguientes maneras:

Sube un archivo de audio

Puedes usar la API de Files para subir un archivo de audio. Usa siempre la API de Files cuando el tamaño total de la solicitud (incluidos los archivos, el mensaje de texto, las instrucciones del sistema, etcétera) sea superior a 20 MB.

El siguiente código sube un archivo de audio y, luego, lo usa en una llamada a 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

Para obtener más información sobre cómo trabajar con archivos multimedia, consulta la API de Files.

Pasa datos de audio intercalados

En lugar de subir un archivo de audio, puedes pasar datos de audio intercalados en la solicitud a 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)
  }
}

Ten en cuenta lo siguiente sobre los datos de audio intercalados:

  • El tamaño máximo de la solicitud es de 20 MB, lo que incluye instrucciones de texto, instrucciones del sistema y archivos proporcionados intercalados. Si el tamaño de tu archivo hará que el tamaño total de la solicitud supere los 20 MB, usa la API de Files para subir un archivo de audio que se usará en la solicitud.
  • Si usas un sample de audio varias veces, es más eficiente subir un archivo de audio.

Cómo obtener una transcripción

Para obtener una transcripción de los datos de audio, simplemente solicítala en la instrucción:

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

Consulta las marcas de tiempo

Puedes hacer referencia a secciones específicas de un archivo de audio con marcas de tiempo del formato MM:SS. Por ejemplo, la siguiente instrucción solicita una transcripción que

  • Comienza a los 2 minutos y 30 segundos desde el principio del archivo.

  • Finaliza a los 3 minutos y 29 segundos desde el principio del archivo.

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

Cuenta tokens

Llama al método countTokens para obtener un recuento de la cantidad de tokens en un archivo de audio. Por ejemplo:

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)

Formatos de audio compatibles

Gemini admite los siguientes tipos de MIME de formato de audio:

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

Detalles técnicos sobre el audio

  • Gemini representa cada segundo de audio como 32 tokens. Por ejemplo, un minuto de audio se representa como 1,920 tokens.
  • Gemini solo puede inferir respuestas a la voz en inglés.
  • Gemini puede “entender” componentes que no son de voz, como cantos de pájaros o sirenas.
  • La duración máxima admitida de los datos de audio en una sola instrucción es de 9.5 horas. Gemini no limita la cantidad de archivos de audio en una sola instrucción. Sin embargo, la duración total combinada de todos los archivos de audio en una sola instrucción no puede exceder las 9.5 horas.
  • Gemini reduce la muestra de los archivos de audio a una resolución de datos de 16 Kbps.
  • Si la fuente de audio contiene varios canales, Gemini los combina en uno solo.

¿Qué sigue?

En esta guía, se muestra cómo generar texto en respuesta a datos de audio. Para obtener más información, consulta los siguientes recursos:

  • Estrategias de indicaciones de archivos: La API de Gemini admite indicaciones con datos de texto, imagen, audio y video, también conocidos como indicaciones multimodales.
  • Instrucciones del sistema: Las instrucciones del sistema te permiten dirigir el comportamiento del modelo según tus necesidades y casos de uso específicos.
  • Orientación sobre seguridad: A veces, los modelos de IA generativa producen resultados inesperados, como resultados imprecisos, sesgados o ofensivos. El procesamiento posterior y la evaluación humana son esenciales para limitar el riesgo de daños que pueden causar estos resultados.