Comprensión de videos

Los modelos de Gemini pueden procesar videos, lo que permite muchos casos de uso de desarrolladores pioneros que, en el pasado, habrían requerido modelos específicos del dominio. Entre algunas de las capacidades de visión de Gemini, se incluyen las siguientes:

  • Describir, segmentar y extraer información de videos de hasta 90 minutos de duración
  • Responde preguntas sobre el contenido de video
  • Cómo hacer referencia a marcas de tiempo específicas dentro de un video

Gemini se diseñó para ser multimodal desde cero y seguimos ampliando los límites de lo posible. En esta guía, se muestra cómo usar la API de Gemini para generar respuestas de texto basadas en entradas de video.

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.

Entrada de video

Puedes proporcionar videos como entrada a Gemini de las siguientes maneras:

  • Sube un archivo de video con la API de File antes de realizar una solicitud a generateContent. Usa este método para archivos de más de 20 MB, videos de más de aproximadamente 1 minuto o cuando quieras volver a usar el archivo en varias solicitudes.
  • Pasa datos de video intercalados con la solicitud a generateContent. Usa este método para archivos más pequeños (<20 MB) y duraciones más cortas.
  • Incluye una URL de YouTube directamente en la instrucción.

Sube un archivo de video

Puedes usar la API de Files para subir un archivo de video. Usa siempre la API de Files cuando el tamaño total de la solicitud (incluido el archivo, el mensaje de texto, las instrucciones del sistema, etcétera) sea superior a 20 MB, la duración del video sea significativa o si deseas usar el mismo video en varias instrucciones.

La API de File acepta formatos de archivo de video directamente. En este ejemplo, se usa el cortometraje de la NASA “Jupiter's Great Red Spot Shrinks and Grows”. Crédito: Centro de vuelo espacial Goddard (GSFC)/David Ladd (2018).

"Jupiter's Great Red Spot Shrinks and Grows" es de dominio público y no muestra a personas identificables. (Lineamientos de uso de imágenes y contenido multimedia de la NASA.)

El siguiente código descarga el video de muestra, lo sube con la API de File, espera a que se procese y, luego, usa la referencia del archivo en una solicitud generateContent.

Python

from google import genai

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

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

response = client.models.generate_content(
    model="gemini-2.0-flash", contents=[myfile, "Summarize this video. Then create a quiz with an answer key based on the information in this video."]
)

print(response.text)

JavaScript

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.mp4",
    config: { mimeType: "video/mp4" },
  });

  const response = await ai.models.generateContent({
    model: "gemini-2.0-flash",
    contents: createUserContent([
      createPartFromUri(myfile.uri, myfile.mimeType),
      "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
    ]),
  });
  console.log(response.text);
}

await main();

Go

file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp4", 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("Summarize this video. Then create a quiz with an answer key based on the information in this video."))
if err != nil {
    log.Fatal(err)
}

printResponse(resp)

REST

VIDEO_PATH="path/to/sample.mp4"
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO

tmp_header_file=upload-header.tmp

echo "Starting file upload..."
curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
  -D ${tmp_header_file} \
  -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}"

echo "Uploading video data..."
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

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

echo "File uploaded successfully. File URI: ${file_uri}"

# --- 3. Generate content using the uploaded video file ---
echo "Generating content from video..."
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":[
          {"file_data":{"mime_type": "'"${MIME_TYPE}"'", "file_uri": "'"${file_uri}"'"}},
          {"text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}]
        }]
      }' 2> /dev/null > response.json

jq -r ".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 video intercalados

En lugar de subir un archivo de video con la API de File, puedes pasar videos más pequeños directamente en la solicitud a generateContent. Esto es adecuado para videos más cortos con un tamaño de solicitud total inferior a 20 MB.

Este es un ejemplo de cómo proporcionar datos de video intercalados:

Python

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

response = client.models.generate_content(
    model='models/gemini-2.0-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(data=video_bytes, mime_type='video/mp4')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

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

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

const contents = [
  {
    inlineData: {
      mimeType: "video/mp4",
      data: base64VideoFile,
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

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

REST

VIDEO_PATH=/path/to/your/video.mp4

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

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":[
            {
              "inline_data": {
                "mime_type":"video/mp4",
                "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'"
              }
            },
            {"text": "Please summarize the video in 3 sentences."}
        ]
      }]
    }' 2> /dev/null

Cómo incluir una URL de YouTube

La API de Gemini y AI Studio admiten URLs de YouTube como datos de archivo Part. Puedes incluir una URL de YouTube con una instrucción que le solicite al modelo que resuma, traduzca o interactúe de alguna otra manera con el contenido del video.

Limitaciones:

  • No puedes subir más de 8 horas de video de YouTube por día.
  • Solo puedes subir 1 video por solicitud.
  • Solo puedes subir videos públicos (no privados ni no listados).

En el siguiente ejemplo, se muestra cómo incluir una URL de YouTube con una instrucción:

Python

response = client.models.generate_content(
    model='models/gemini-2.0-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=9hE5-98ZeCg')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro" });
const result = await model.generateContent([
  "Please summarize the video in 3 sentences.",
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
]);
console.log(result.response.text());

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GOOGLE_API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
  genai.FileData{URI: "https://www.youtube.com/watch?v=9hE5-98ZeCg"},
  genai.Text("Please summarize the video in 3 sentences."))
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)
  }
}

REST

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": "Please summarize the video in 3 sentences."},
            {
              "file_data": {
                "file_uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
              }
            }
        ]
      }]
    }' 2> /dev/null

Consulta las marcas de tiempo en el contenido

Puedes hacer preguntas sobre momentos específicos del video con marcas de tiempo del formato MM:SS.

Python

prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?" # Adjusted timestamps for the NASA video

JavaScript

const prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?";

Go

    prompt := []genai.Part{
        genai.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
         // Adjusted timestamps for the NASA video
        genai.Text("What are the examples given at 00:05 and " +
            "00:10 supposed to show us?"),
    }

REST

PROMPT="What are the examples given at 00:05 and 00:10 supposed to show us?"

Transcribe videos y proporciona descripciones visuales

Los modelos de Gemini pueden transcribir y proporcionar descripciones visuales del contenido de video mediante el procesamiento de la pista de audio y los fotogramas visuales. Para las descripciones visuales, el modelo muestrea el video a una velocidad de 1 fotograma por segundo. Esta tasa de muestreo puede afectar el nivel de detalle de las descripciones, en especial en el caso de los videos con imágenes que cambian rápidamente.

Python

prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

JavaScript

const prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions.";

Go

    prompt := []genai.Part{
        genai.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
        genai.Text("Transcribe the audio from this video, giving timestamps for salient events in the video. Also " +
            "provide visual descriptions."),
    }

REST

PROMPT="Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

Formatos de video compatibles

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

  • video/mp4
  • video/mpeg
  • video/mov
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

Detalles técnicos sobre los videos

  • Modelos y contexto compatibles: Todos los modelos Gemini 2.0 y 2.5 pueden procesar datos de video.
    • Los modelos con una ventana de contexto de 2 millones de tokens pueden procesar videos de hasta 2 horas de duración, mientras que los modelos con una ventana de contexto de 1 millón de tokens pueden procesar videos de hasta 1 hora de duración.
  • Procesamiento de la API de File: Cuando se usa la API de File, los videos se muestrean a 1 fotograma por segundo (FPS) y el audio se procesa a 1 Kbps (canal único). Las marcas de tiempo se agregan cada segundo.
    • Estas tarifas están sujetas a cambios en el futuro para mejorar la inferencia.
  • Cálculo de tokens: Cada segundo de video se segmenta de la siguiente manera:
    • Fotogramas individuales (muestreados a 1 FPS): 258 tokens por fotograma.
    • Audio: 32 tokens por segundo
    • También se incluyen los metadatos.
    • Total: Aproximadamente 300 tokens por segundo de video.
  • Formato de marca de tiempo: Cuando te refieras a momentos específicos de un video en tu instrucción, usa el formato MM:SS (p.ej., 01:15 durante 1 minuto y 15 segundos).
  • Prácticas recomendadas:
    • Usa solo un video por solicitud de instrucción para obtener mejores resultados.
    • Si combinas texto y un solo video, coloca la instrucción de texto después de la parte de video en el array contents.
    • Ten en cuenta que las secuencias de acción rápidas pueden perder detalles debido a la tasa de muestreo de 1 FPS. Si es necesario, considera ralentizar estos clips.

¿Qué sigue?

En esta guía, se muestra cómo subir archivos de video y generar salidas de texto a partir de entradas de video. Para obtener más información, consulta los siguientes recursos:

  • Instrucciones del sistema: Las instrucciones del sistema te permiten dirigir el comportamiento del modelo según tus necesidades y casos de uso específicos.
  • API de Files: Obtén más información para subir y administrar archivos para usarlos con Gemini.
  • 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.
  • Orientación de 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.