Comprensión de videos

Los modelos de Gemini pueden procesar videos, lo que permite muchos casos de uso de desarrolladores de vanguardia que históricamente habrían requerido modelos específicos del dominio. Estas son algunas de las capacidades de visión de Gemini:

  • Describe, segmenta y extrae información de videos
  • Responde preguntas sobre el contenido de video
  • Cómo hacer referencia a marcas de tiempo específicas dentro de un video

Gemini se creó 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.

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 1 minuto aproximadamente o cuando quieras reutilizar 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 (menos de 20 MB) y duraciones más cortas.
  • Incluye una URL de YouTube directamente en la instrucción.

Cómo subir un archivo de video

Puedes usar la API de Files para subir un archivo de video. Siempre usa la API de Files cuando el tamaño total de la solicitud (incluido el archivo, la instrucción de texto, las instrucciones del sistema, etcétera) sea superior a 20 MB, la duración del video sea significativa o si tienes la intención de usar el mismo video en varias instrucciones. La API de File acepta formatos de archivos de video directamente.

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 de generateContent.

Python

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-2.5-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({});

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.5-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

uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", nil)

parts := []*genai.Part{
    genai.NewPartFromText("Summarize this video. Then create a quiz with an answer key based on the information in this video."),
    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

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" \
  -H "x-goog-api-key: $GEMINI_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.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_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 total de solicitud inferior a 20 MB.

A continuación, se muestra 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.5-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({});
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.5-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.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_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

Incluye 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 pida al modelo que resuma, traduzca o interactúe de alguna otra manera con el contenido del video.

Limitaciones:

  • En el nivel gratuito, no puedes subir más de 8 horas de videos de YouTube por día.
  • En el nivel pagado, no hay límites basados en la duración del video.
  • En el caso de los modelos anteriores a la versión 2.5, solo puedes subir 1 video por solicitud. En el caso de los modelos posteriores a la versión 2.5, puedes subir un máximo de 10 videos 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.5-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

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

  parts := []*genai.Part{
      genai.NewPartFromText("Please summarize the video in 3 sentences."),
      genai.NewPartFromURI("https://www.youtube.com/watch?v=9hE5-98ZeCg","video/mp4"),
  }

  contents := []*genai.Content{
      genai.NewContentFromParts(parts, genai.RoleUser),
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-2.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

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": "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 usando marcas de tiempo con el 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.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
         // Adjusted timestamps for the NASA video
        genai.NewPartFromText("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?"

Transcribir videos y proporcionar descripciones visuales

Los modelos de Gemini pueden transcribir y proporcionar descripciones visuales del contenido de video procesando 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 frecuencia 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.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
        genai.NewPartFromText("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."

Personaliza el procesamiento de videos

Puedes personalizar el procesamiento de video en la API de Gemini configurando intervalos de recorte o proporcionando un muestreo de frecuencia de fotogramas personalizado.

Cómo establecer intervalos de recorte

Puedes cortar videos especificando videoMetadata con compensaciones iniciales y finales.

Python

response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=XEzRZ35urlk'),
                video_metadata=types.VideoMetadata(
                    start_offset='1250s',
                    end_offset='1570s'
                )
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

Cómo establecer una frecuencia de fotogramas personalizada

Puedes establecer un muestreo de la frecuencia de fotogramas personalizado pasando un argumento fps a videoMetadata.

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.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=video_bytes,
                    mime_type='video/mp4'),
                video_metadata=types.VideoMetadata(fps=5)
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

De forma predeterminada, se muestrea 1 fotograma por segundo (FPS) del video. Es posible que desees establecer un valor de FPS bajo (inferior a 1) para los videos largos. Esto es especialmente útil para los videos que son mayormente estáticos (p.ej., conferencias). Si quieres capturar más detalles en imágenes que cambian rápidamente, considera establecer un valor de FPS más alto.

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 admitidos: Todos los modelos de 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 con la resolución de medios predeterminada o de 6 horas con la resolución de medios baja, 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 con la resolución de medios predeterminada o de 3 horas con la resolución de medios baja.
  • 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 (un solo canal). Las marcas de tiempo se agregan cada segundo.
    • Estas tasas están sujetas a cambios en el futuro para mejorar la inferencia.
  • Cálculo de tokens: Cada segundo de video se tokeniza de la siguiente manera:
    • Fotogramas individuales (muestreados a 1 FPS):
      • Si mediaResolution se establece en un valor bajo, los fotogramas se tokenizan a 66 tokens por fotograma.
      • De lo contrario, los fotogramas se tokenizan a 258 tokens por fotograma.
    • Audio: 32 tokens por segundo
    • También se incluyen los metadatos.
    • Total: Aproximadamente 300 tokens por segundo de video en la resolución de medios predeterminada o 100 tokens por segundo de video en la resolución de medios baja
  • 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:
    • Para obtener resultados óptimos, usa solo un video por solicitud de instrucción.
    • Si combinas texto y un solo video, coloca la instrucción de texto después de la parte del 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 reducir la velocidad de esos clips.

¿Qué sigue?

En esta guía, se muestra cómo subir archivos de video y generar resultados 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 instrucciones con archivos: La API de Gemini admite instrucciones con datos de texto, imagen, audio y video, lo que también se conoce como instrucciones multimodales.
  • Orientación sobre seguridad: A veces, los modelos de IA generativa producen resultados inesperados, como resultados inexactos, sesgados u ofensivos. El procesamiento posterior y la evaluación humana son fundamentales para limitar el riesgo de daño que pueden causar estos resultados.