Compreensão do vídeo

Os modelos Gemini podem processar vídeos, permitindo muitos casos de uso de desenvolvedores de fronteira que, historicamente, exigiriam modelos específicos de domínio. Alguns dos recursos de visão do Gemini incluem a capacidade de:

  • Descrever, segmentar e extrair informações de vídeos com até 90 minutos de duração
  • Responder a perguntas sobre o conteúdo do vídeo
  • Fazer referência a marcações de tempo específicas em um vídeo

O Gemini foi criado para ser multimodal desde o início, e continuamos avançando os limites do que é possível. Este guia mostra como usar a API Gemini para gerar respostas de texto com base em entradas de vídeo.

Antes de começar

Antes de chamar a API Gemini, verifique se você tem o SDK de sua escolha instalado e uma chave da API Gemini configurada e pronta para uso.

Entrada de vídeo

Você pode fornecer vídeos como entrada para o Gemini das seguintes maneiras:

  • Envie um arquivo de vídeo usando a API File antes de fazer uma solicitação para generateContent. Use esse método para arquivos maiores que 20 MB, vídeos com mais de um minuto ou quando você quiser reutilizar o arquivo em várias solicitações.
  • Transmita dados de vídeo inline com a solicitação para generateContent. Use esse método para arquivos menores (menos de 20 MB) e durações mais curtas.
  • Inclua um URL do YouTube diretamente no comando.

Fazer upload de um arquivo de vídeo

É possível usar a API Files para fazer upload de um arquivo de vídeo. Sempre use a API Files quando o tamanho total da solicitação (incluindo o arquivo, o comando de texto, as instruções do sistema etc.) for maior que 20 MB, a duração do vídeo for significativa ou se você pretende usar o mesmo vídeo em vários comandos.

A API File aceita formatos de arquivo de vídeo diretamente. Este exemplo usa o filme curto da NASA "Jupiter's Great Red Spot Shrinks and Grows". Crédito: Centro de Voos Espaciais Goddard (GSFC)/David Ladd (2018).

"Jupiter's Great Red Spot Shrinks and Grows" está no domínio público e não mostra pessoas identificáveis. (Diretrizes de uso de imagens e mídia da NASA.)

O código a seguir faz o download do vídeo de exemplo, faz o upload dele usando a API File, espera que ele seja processado e, em seguida, usa a referência do arquivo em uma solicitação 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 saber mais sobre como trabalhar com arquivos de mídia, consulte a API Files.

Transmitir dados de vídeo inline

Em vez de fazer upload de um arquivo de vídeo usando a API File, é possível transmitir vídeos menores diretamente na solicitação para generateContent. Isso é adequado para vídeos mais curtos com menos de 20 MB de tamanho de solicitação.

Confira um exemplo de como fornecer dados de vídeo inline:

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

Incluir um URL do YouTube

A API Gemini e o AI Studio oferecem suporte a URLs do YouTube como Part de dados de arquivo. É possível incluir um URL do YouTube com um comando que pede ao modelo para resumir, traduzir ou interagir com o conteúdo do vídeo.

Limitações:

  • Não é possível enviar mais de oito horas de vídeo do YouTube por dia.
  • Você só pode enviar um vídeo por solicitação.
  • Só é possível enviar vídeos públicos, não privados ou não listados.

O exemplo a seguir mostra como incluir um URL do YouTube com uma solicitação:

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

Consulte as marcações de tempo no conteúdo

Você pode fazer perguntas sobre pontos específicos no vídeo usando carimbos de data/hora do formulário 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?"

Transcrever vídeos e fornecer descrições visuais

Os modelos Gemini podem transcrever e fornecer descrições visuais do conteúdo de vídeo processando a faixa de áudio e os frames visuais. Para descrições visuais, o modelo faz a amostragem do vídeo a uma taxa de 1 frame por segundo. Essa taxa de amostragem pode afetar o nível de detalhes nas descrições, principalmente em vídeos com mudanças visuais rápidas.

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 vídeo compatíveis:

O Gemini oferece suporte aos seguintes tipos MIME de formato de vídeo:

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

Detalhes técnicos sobre vídeos

  • Modelos e contexto com suporte: todos os modelos Gemini 2.0 e 2.5 podem processar dados de vídeo.
    • Os modelos com uma janela de contexto de 2 milhões podem processar vídeos de até 2 horas, enquanto os modelos com uma janela de contexto de 1 milhão podem processar vídeos de até 1 hora.
  • Processamento da API File: ao usar a API File, os vídeos são amostrados a 1 frame por segundo (QPS) e o áudio é processado a 1 Kbps (canal único). Os carimbos de data/hora são adicionados a cada segundo.
    • Essas taxas estão sujeitas a mudanças no futuro para melhorias na inferência.
  • Cálculo de tokens: cada segundo de vídeo é tokenizado da seguinte maneira:
    • Frames individuais (amostrados a 1 QPS): 258 tokens por frame.
    • Áudio: 32 tokens por segundo.
    • Os metadados também são incluídos.
    • Total: aproximadamente 300 tokens por segundo de vídeo.
  • Formato de carimbo de data/hora: ao se referir a momentos específicos em um vídeo no comando, use o formato MM:SS (por exemplo, 01:15 por 1 minuto e 15 segundos).
  • Práticas recomendadas:
    • Use apenas um vídeo por comando para ter os melhores resultados.
    • Se você combinar texto e um único vídeo, coloque o comando de texto após a parte de vídeo na matriz contents.
    • Sequências de ação rápidas podem perder detalhes devido à taxa de amostragem de 1 QPS. Diminua a velocidade desses clipes, se necessário.

A seguir

Este guia mostra como fazer upload de arquivos de vídeo e gerar saídas de texto a partir de entradas de vídeo. Para saber mais, consulte os seguintes recursos:

  • Instruções do sistema: permitem orientar o comportamento do modelo com base nas suas necessidades e casos de uso específicos.
  • API Files: saiba como fazer upload e gerenciar arquivos para uso com o Gemini.
  • Estratégias de solicitação de arquivo: a API Gemini oferece suporte a solicitações com dados de texto, imagem, áudio e vídeo, também conhecidas como solicitações multimodais.
  • Orientações de segurança: às vezes, os modelos de IA generativa produzem resultados inesperados, como resultados imprecisos, parciais ou ofensivos. O pós-processamento e a avaliação humana são essenciais para limitar o risco de danos causados por essas saídas.