Pemahaman video

Untuk mempelajari pembuatan video, lihat panduan Gemini Omni Flash.

Model Gemini dapat memproses video, sehingga memungkinkan banyak kasus penggunaan developer terdepan yang secara historis memerlukan model khusus domain. Beberapa kemampuan vision Gemini mencakup kemampuan untuk: mendeskripsikan, mensegmentasikan, dan mengekstrak informasi dari video, menjawab pertanyaan tentang konten video, dan merujuk ke stempel waktu tertentu dalam video.

Anda dapat memberikan video sebagai input ke Gemini dengan cara berikut:

Metode masukan Ukuran maks Kasus penggunaan yang direkomendasikan
File API 20 GB (berbayar) / 2 GB (gratis) File besar (100 MB+), video panjang (10 menit+), file yang dapat digunakan kembali.
Pendaftaran Cloud Storage 2 GB (per file, tanpa batas penyimpanan) File besar (100 MB+), video panjang (10 menit+), file persisten yang dapat digunakan kembali.
Data Sebaris < 100 MB File kecil (<100 MB), durasi singkat (<1 menit), input satu kali.
URL YouTube T/A Video YouTube publik.

Catatan: File API direkomendasikan untuk sebagian besar kasus penggunaan, terutama untuk file yang lebih besar dari 100 MB atau jika Anda ingin menggunakan kembali file di beberapa permintaan.

Untuk mempelajari metode input file lainnya, seperti menggunakan URL eksternal atau file yang disimpan di Google Cloud, lihat panduan Metode input file.

Mengupload file video

Kode berikut mendownload video sampel, menguploadnya menggunakan Files API, menunggu hingga diproses, lalu menggunakan referensi file yang diupload untuk meringkas video.

Python

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-3.8-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-3.8-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-3.8-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}&qu>ot; \
  -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 "Upl>oading vide>o 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-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: applicati>on/json'>; \
    -X POST \
    -d '{
      "contents": [{
        &quot;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

Selalu gunakan Files API jika ukuran total permintaan (termasuk file, perintah teks, petunjuk sistem, dll.) lebih besar dari 20 MB, durasi video signifikan, atau jika Anda ingin menggunakan video yang sama di beberapa perintah. File API menerima format file video secara langsung.

Untuk mempelajari lebih lanjut cara menggunakan file media, lihat Files API.

Meneruskan data video sebaris

Daripada mengupload file video menggunakan File API, Anda dapat meneruskan video yang lebih kecil langsung dalam permintaan ke generateContent. Hal ini cocok untuk video yang lebih pendek dengan ukuran total permintaan di bawah 20 MB.

Berikut adalah contoh pemberian data video sebaris:

Python

from google import genai
from google.genai import types

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

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-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.';)
        ]
    )
)
print(response.text)

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-3.8-flash",
  contents: contents,
});
console.log(response.text);

REST

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

if [[ "$(base64 --vers>&ion 21)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-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

Meneruskan URL YouTube

Anda dapat meneruskan URL YouTube langsung ke Gemini API sebagai bagian dari permintaan Anda sebagai berikut:

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-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.')
        ]
    )
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const contents = [
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: contents,
});
console.log(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-3.8-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-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

Batasan:

  • Untuk paket gratis, Anda tidak dapat mengupload lebih dari 8 jam video YouTube per hari.
  • Untuk paket berbayar, tidak ada batasan berdasarkan durasi video.
  • Untuk model sebelum Gemini 2.5, Anda hanya dapat mengupload 1 video per permintaan. Untuk model Gemini 2.5 dan yang lebih baru, Anda dapat mengupload maksimal 10 video per permintaan.
  • Anda hanya dapat mengupload video publik (bukan video pribadi atau tidak publik).

Pemahaman video agentic

Secara default, input video menggunakan pemrosesan statis (mengekstrak frame pada 1 FPS). Model Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, dan 3.5 Flash Lite juga mendukung pemahaman video agentic, dengan model yang secara dinamis menjelajahi linimasa video , memeriksa transkrip secara selektif, dan menyesuaikan kecepatan frame serta resolusi secara adaptif saat runtime berdasarkan perintah.

Mode Deskripsi Model yang didukung
Statis (default) Mengekstrak frame pada kecepatan tetap (1 FPS) dan menempatkannya ke dalam konteks dalam satu kali proses. Berfungsi dengan baik untuk klip pendek. Semua model Gemini
Agentic Model ini secara dinamis menavigasi linimasa video, hanya memuat konten yang diperlukan berdasarkan perintah. Hingga 88% lebih hemat token dan ~7% kualitas lebih tinggi pada konten berdurasi panjang. Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite

Memilih mode pemrosesan

Sebagai panduan umum, mulailah dengan mode agentic, terutama saat mengoptimalkan kualitas respons atau efisiensi token.

  • Agentic: Video panjang atau kueri yang menargetkan momen tertentu. Model ini secara dinamis menavigasi linimasa untuk menargetkan informasi yang relevan secara kontekstual tanpa mengisi jendela konteks.
  • Statis: Kueri yang sensitif terhadap latensi pada klip pendek (di bawah 5 menit), atau kasus saat presisi tingkat frame diperlukan di seluruh klip.

Menetapkan mode pemrosesan

Python

import time
from google import genai
from google.genai import types

client = genai.Client()

video_file = client.files.upload(file="path/to/lecture.mp4")

while video_file.state.name == "PROCESSING":
    time.sleep(2)
    video_file = client.files.get(name=video_file.name)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_file.uri,
            mime_type=video_file.mime_type,
            media_processing="AGENTIC",
        ),
        "What are the three main arguments presented?",
    ],
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

let videoFile = await ai.files.upload({
  file: "path/to/lecture.mp4",
  config: { mimeType: "video/mp4" },
});

while (videoFile.state === "PROCESSING&>quot;) {
  await new Promise((resolve) = setTimeout(resolve, 2000));
  videoFile = await ai.files.get({ name: videoFile.name });
}

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: videoFile.uri,
            mimeType: videoFile.mimeType,
          },
          mediaProcessing: "AGENTIC",
        },
        { text: "What are the three main arguments presented?" },
      ],
    },
  ],
});
console.log(response.text);

Go

uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/lecture.mp4", nil)
parts := []*genai.Part{
    {
        &FileData: genai.FileData{
            FileURI:  uploadedFile.URI,
            MIMEType: uploadedFile.MIMEType,
        },
        MediaProcessing: genai.MediaProcessingAgentic,
    },
    genai.NewPartFromText("What are the three main arguments presented?"),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${file_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing&quot;: "AGENTIC"
        },
        {"text": "What are the three main arguments presented?"}
      ]
    }]
  }'

Catatan: Untuk memverifikasi bahwa pemrosesan agentic digunakan, periksa response.candidates[0].content.parts. Keberadaan bagian tool_call dan tool_response dengan jenis alat MEDIA_PROCESSING menunjukkan bahwa model secara dinamis menavigasi video.

Catatan: Tidak seperti alat sisi server lainnya (seperti Google Penelusuran atau konteks URL), video agentic tidak memerlukan setelan include_server_side_tool_invocations=True di ToolConfig agar panggilan dan hasil alat dapat ditampilkan atau di-streaming. Bagian tool_call dan tool_response untuk navigasi video akan ditampilkan secara otomatis saat media_processing="AGENTIC" ditetapkan pada bagian input mana pun.

Struktur respons

Saat pemrosesan agentic diaktifkan, respons akan menyertakan bagian tambahan yang menampilkan jalur navigasi internal:

  • tool_call bagian (tool_type: "MEDIA_PROCESSING"): ditampilkan setiap kali model meminta segmen video atau transkrip audio.
  • tool_response bagian (tool_type: "MEDIA_PROCESSING"): hasil dari setiap operasi pemuatan.

Anda tidak perlu menangani atau membalas bagian ini secara manual: teruskan respons lengkap sebagai histori percakapan dan bagian ini akan ditangani secara otomatis.

Jika include_thoughts=True ditetapkan di ThinkingConfig, langkah-langkah penalaran akan muncul sebagai bagian thought: true yang disisipkan dengan pasangan panggilan/respons alat. Jika pemikiran dinonaktifkan, teks pemikiran akan dihilangkan, tetapi bagian alat masih ada.

Contoh berikut menunjukkan payload respons dengan bagian panggilan dan respons alat yang disisipkan:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "thought": true,
            "text": "Inspecting transcript for key discussion topics..."
          },
          {
            "thought_signature": "sig_A",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_B",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Loading visual frames to verify slide content..."
          },
          {
            "thought_signature": "sig_C",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_D",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Synthesizing answer from gathered evidence..."
          },
          {
            "text": "The three main arguments presented in the lecture are...",
            "thought_signature": "sig_E"
          }
        ]
      }
    }
  ]
}

Mencampur mode pemrosesan di seluruh video

Anda dapat menetapkan mode pemrosesan yang berbeda untuk setiap Bagian video dalam permintaan yang sama:

Python

from google import genai
from google.genai import types

client = genai.Client()

lecture = client.files.upload(file="path/to/long-lecture.mp4")
experiment = client.files.upload(file="path/to/short-experiment.mp4")

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_uri(
            file_uri=lecture.uri,
            mime_type=lecture.mime_type,
            media_processing="AGENTIC",  # Use agentic video understanding
        ),
        types.Part.from_uri(
            file_uri=experiment.uri,
            mime_type=experiment.mime_type,
            media_processing="STATIC",  # Use static processing
        ),
        "Compare the lecture content with the experiment results.",
    ],
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const lecture = await ai.files.upload({
  file: "path/to/long-lecture.mp4",
  config: { mimeType: "video/mp4" },
});
const experiment = await ai.files.upload({
  file: "path/to/short-experiment.mp4",
  config: { mimeType: "video/mp4" },
});

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: lecture.uri,
            mimeType: lecture.mimeType,
          },
          mediaProcessing: "AGENTIC", // Use agentic video understanding
        },
        {
          fileData: {
            fileUri: experiment.uri,
            mimeType: experiment.mimeType,
          },
          mediaProcessing: "STATIC", // Use static processing
        },
        { text: "Compare the lecture content with the experiment results." },
      ],
    },
  ],
});
console.log(response.text);

Go

lecturePart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  lectureFile.URI,
        MIMEType: lectureFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingAgentic, // Use agentic
}
experimentPart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  experimentFile.URI,
        MIMEType: experimentFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingStatic, // Use static
}
parts := []*genai.Part{
    lecturePart,
    experimentPart,
    genai.NewPartFromText("Compare the lecture content with the experiment results."),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${lecture_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "AGENTIC"
        },
        {
          "file_data": {
            "file_uri": "'${experiment_uri}'",
            "mime_type": &quot;video/mp4"
          },
          "media_processing": "STATIC"
        },
        {"text": "Compare the lecture content with the experiment results."}
      ]
    }]
  }'

Menggunakan context caching untuk video panjang

Untuk video yang lebih panjang dari 10 menit, atau jika Anda berencana membuat beberapa permintaan terhadap file video yang sama, gunakan context caching untuk mengurangi biaya dan meningkatkan latensi. Context caching memungkinkan Anda memproses video satu kali dan menggunakan kembali token untuk kueri berikutnya, sehingga ideal untuk sesi chat atau analisis berulang konten berdurasi panjang.

Merujuk ke stempel waktu dalam konten

Anda dapat mengajukan pertanyaan tentang poin waktu tertentu dalam video menggunakan stempel waktu dalam format 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?"

Mengekstrak insight mendetail dari video

Model Gemini menawarkan kemampuan yang canggih untuk memahami konten video dengan memproses informasi dari streaming audio dan visual. Hal ini memungkinkan Anda mengekstrak serangkaian detail yang kaya, termasuk membuat deskripsi tentang apa yang terjadi dalam video dan menjawab pertanyaan tentang kontennya.

Untuk deskripsi visual, model mengambil sampel video dengan kecepatan 1 frame per detik (FPS). Kecepatan pengambilan sampel default ini berfungsi dengan baik untuk sebagian besar konten, tetapi perhatikan bahwa kecepatan ini mungkin tidak dapat menangkap detail dalam video dengan gerakan cepat atau perubahan adegan yang cepat. Untuk konten dengan gerakan tinggi seperti itu, pertimbangkan untuk menetapkan kecepatan frame kustom.

Python

prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

JavaScript

const prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.";

Go

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
        genai.NewPartFromText("Describe the key events in this video, providing both audio and visual details. " +
      "Include timestamps for salient moments."),
    }

REST

PROMPT="Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

Menyesuaikan pemrosesan video

Anda dapat menyesuaikan pemrosesan video di Gemini API dengan menetapkan interval kliping atau memberikan pengambilan sampel kecepatan frame kustom. Opsi penyesuaian ini hanya didukung saat memproses video dalam mode "static".

Menetapkan interval kliping

Anda dapat mengklip video dengan menentukan videoMetadata dengan offset awal dan akhir.

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-3.8-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.')
        ]
    )
)

JavaScript

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-3.8-flash';

async function main() {
const contents = [
  {
    role: 'user',
    parts: [
      {
        fileData: {
          fileUri: 'https://www.youtube.com/watch?v=9hE5-98ZeCg',
          mimeType: 'video/*',
        },
        videoMetadata: {
          startOffset: '40s',
          endOffset: '80s',
        }
      },
      {
        text: 'Please summarize the video in 3 sentences.',
      },
    ],
  },
];

const response = await ai.models.generateContent({
  model,
  contents,
});

console.log(response.text)

}

await main();

Menetapkan kecepatan frame kustom

Anda dapat menetapkan pengambilan sampel kecepatan frame kustom dengan meneruskan argumen fps ke videoMetadata.

Python

from google import genai
from google.genai import types

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

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-3.8-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.')
        ]
    )
)

Secara default, 1 frame per detik (FPS) diambil sampelnya dari video. Anda mungkin ingin menetapkan FPS rendah (< 1) untuk video panjang. Hal ini sangat berguna untuk video yang sebagian besar statis (misalnya, kuliah). Gunakan FPS yang lebih tinggi untuk video yang memerlukan analisis temporal terperinci, seperti pemahaman tindakan cepat atau pelacakan gerakan berkecepatan tinggi.

Format video yang didukung

Gemini mendukung jenis MIME format video berikut:

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

Detail teknis tentang video

  • Model dan konteks yang didukung: Semua model Gemini dapat memproses data video.
    • Model dengan jendela konteks 1 juta dapat memproses video hingga 3 jam secara default (pada resolusi media rendah), atau hingga 1 jam pada resolusi media tinggi.
  • Mode pemrosesan: Model Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite, dan yang lebih baru mendukung dua mode pemrosesan video:
    • Statis: Frame diekstrak pada 1 FPS dan ditempatkan ke dalam konteks (default untuk semua model). Audio diproses pada 1 Kbps (satu channel). Stempel waktu ditambahkan setiap detik. Paling cocok untuk klip pendek atau saat setiap frame penting (seperti pemeriksaan frame demi frame). Perhatikan bahwa urutan tindakan cepat mungkin kehilangan detail karena kecepatan pengambilan sampel 1 FPS.
    • Agentic: Model ini secara dinamis menavigasi video, memuat transkrip dan/atau frame dan/atau audio sesuai permintaan. Hal ini menggunakan token hingga 88% lebih sedikit untuk konten berdurasi panjang, meskipun navigasi dapat sedikit meningkatkan Waktu ke Token Pertama (TTFT) pada klip pendek (<5 menit) karena penalaran internal dan round-trip alat sebelum pembuatan dimulai. Respons mencakup bagian panggilan dan respons alat MEDIA_PROCESSING untuk mempertahankan konteks penalaran di seluruh giliran. Paling cocok untuk video panjang guna mengoptimalkan biaya token dan kualitas respons. Didukung di Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, dan 3.5 Flash Lite. Lihat Pemahaman video agentic untuk mengetahui detailnya.
  • Penghitungan token (mode statis): Setiap detik video di-tokenisasi sebagai berikut:
    • Frame individual (diambil sampelnya pada 1 FPS):
      • Jika media_resolution ditetapkan ke rendah, frame akan di-tokenisasi pada 66 token per frame.
      • Jika tidak, frame akan di-tokenisasi pada 258 token per frame.
    • Audio: 32 token per detik.
    • Metadata juga disertakan.
    • Total: Sekitar 100 token per detik video pada resolusi media default (rendah), atau sekitar 300 token per detik video pada resolusi media tinggi.
  • Penghitungan token (mode agentic): Penggunaan token bervariasi berdasarkan kompleksitas konten dan strategi navigasi model. Token penalaran navigasi yang dibuat selama eksplorasi video dihitung sebagai token pemikiran (thoughts_token_count), sedangkan frame, audio, dan transkrip yang dimuat sesuai permintaan dihitung sebagai token perintah alat (tool_use_prompt_token_count). Pemrosesan agentic biasanya menggunakan total token hingga 88% lebih sedikit daripada pemrosesan statis untuk konten berdurasi panjang karena model hanya memuat transkrip dan/atau frame dan/atau audio yang diperlukan untuk menjawab perintah (lihat panduan token).
  • Resolusi media: Gemini 3 memperkenalkan kontrol terperinci atas pemrosesan vision multimodal dengan parameter media_resolution. Parameter media_resolution menentukan jumlah maksimum token yang dialokasikan per frame gambar atau video input. Resolusi yang lebih tinggi meningkatkan kemampuan model untuk membaca teks halus atau mengidentifikasi detail kecil, tetapi meningkatkan penggunaan token dan latensi. Parameter media_resolution dan media_processing bersifat independen: Anda dapat menetapkan keduanya pada Bagian video yang sama.

Untuk mengetahui detail selengkapnya tentang penghitungan token, lihat panduan token.

  • Format stempel waktu: Saat merujuk ke momen tertentu dalam video di dalam perintah Anda, gunakan format MM:SS (misalnya, 01:15 untuk 1 menit dan 15 detik).
  • Penempatan perintah: Jika menggabungkan teks dan satu video, tempatkan perintah teks setelah bagian video dalam array contents.

Langkah berikutnya

  • Resolusi media: Kontrol resolusi frame video untuk menyeimbangkan kualitas dan penggunaan token.
  • Token: Pahami cara konten video di-tokenisasi dalam mode pemrosesan statis dan agentic.
  • Petunjuk sistem: Petunjuk sistem memungkinkan Anda mengarahkan perilaku model berdasarkan kebutuhan dan kasus penggunaan tertentu.
  • Files API: Pelajari lebih lanjut cara mengupload dan mengelola file untuk digunakan dengan Gemini.
  • Strategi multimodal prompting file: Gemini API mendukung multimodal prompting dengan data teks, gambar, audio, dan video, yang juga dikenal sebagai multimodal prompting.
  • Panduan keamanan: Terkadang model AI generatif menghasilkan output yang tidak terduga, seperti output yang tidak akurat, bias, atau menyinggung. Pascapemrosesan dan evaluasi manual sangat penting untuk membatasi risiko bahaya dari output tersebut.