Pemahaman video

Anda dapat menambahkan video ke permintaan Gemini untuk melakukan tugas yang melibatkan pemahaman konten video yang disertakan. Halaman ini menunjukkan cara menambahkan video ke permintaan Anda ke Gemini di Gemini Enterprise Agent Platform menggunakan konsol Google Cloud dan Agent Platform API.

Model yang didukung

Tabel berikut mencantumkan model yang mendukung pemahaman video:

Model Detail media Jenis MIME
  • Durasi video maksimum (dengan audio): 10 detik
  • Durasi video maksimum (tanpa audio): 10 detik
  • Jumlah maksimum video per perintah: 3
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Durasi video maksimum (dengan audio): 15 detik
  • Durasi video maksimum (tanpa audio): 15 detik
  • Durasi video input maksimum (pemahaman video): 10 menit
  • Durasi video input maksimum (pengeditan): 15 detik
  • Durasi video input maksimum (ekstensi): Durasi berapa pun (menggunakan hingga 10 detik terakhir)
  • Durasi video input maksimum (peningkatan skala): 15 detik
  • Durasi video output (pembuatan dan pengeditan): 3 hingga 15 detik (3 hingga 10 detik untuk frame pertama dan terakhir)
  • Durasi video output (ekstensi): 3 hingga 10 detik (digabungkan hingga 30 detik terakhir video input)
  • Jumlah maksimum video per perintah: 3
  • Rasio aspek yang didukung: 16:9, 9:16
  • Resolusi yang didukung: 360p, 720p, 1080p, 4k
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Durasi video maksimum (dengan audio): 10 detik
  • Durasi video maksimum (tanpa audio): 10 detik
  • Jumlah maksimum video per perintah: 3
  • Rasio aspek yang didukung: 16:9, 9:16
  • Resolusi yang didukung: 360p, 720p, 1080p, 4k
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Jumlah maksimum file video input per perintah: 10
  • URL YouTube maksimum per perintah: 1
  • Durasi video maksimum (tanpa audio): Seperti yang didukung oleh jendela konteks token 128k (sekitar 25 menit).
  • Ukuran bagian inline maksimum: 256 MB
  • Ukuran file maksimum per file dari Cloud Storage: 2 GiB dikurangi 500 KiB
  • Ukuran file maksimum per file dari URL HTTP atau HTTPS publik: 15 MiB
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Durasi video maksimum (dengan audio): Sekitar 45 menit
  • Durasi video maksimum (tanpa audio): Sekitar 1 jam
  • Jumlah maksimum video per perintah: 10
  • Ukuran bagian inline maksimum (GenerateContent API): 256 MB
  • Ukuran file maksimum per file dari Cloud Storage: 2 GiB dikurangi 500 KiB
  • Ukuran file maksimum per file dari URL HTTP atau HTTPS publik: 15 MiB
  • Token resolusi default per frame: 70
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Resolusi input standar: 768 x 768 (1 FPS)
  • Resolusi output minimum Avatar Live: 704 x 1280 (potret) atau 1280 x 704 (lanskap) pada 24 FPS
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Jumlah maksimum file video input per perintah: 10
  • URL YouTube maksimum per perintah: 1
  • Durasi video maksimum (tanpa audio): Seperti yang didukung oleh jendela konteks 65.536 token (sekitar 12 menit).
  • Ukuran bagian inline maksimum: 256 MB
  • Ukuran file maksimum per file dari Cloud Storage: 2 GiB dikurangi 500 KiB
  • Ukuran file maksimum per file dari URL HTTP atau HTTPS publik: 15 MiB
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Durasi video maksimum (dengan audio): Sekitar 45 menit
  • Durasi video maksimum (tanpa audio): Sekitar 1 jam
  • Jumlah maksimum video per perintah: 10 (hingga 1 URL HTTP atau HTTPS di endpoint yang tidak dimigrasikan)
  • Ukuran bagian inline maksimum: 256 MB
  • Ukuran file maksimum per file dari Cloud Storage: 2 GiB dikurangi 500 KiB
  • Ukuran file maksimum per file dari URL HTTP atau HTTPS publik: 15 MiB
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Resolusi standar: 768 x 768
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp

Untuk mengetahui daftar bahasa yang didukung oleh model Gemini, lihat informasi model Model Google. Untuk mempelajari lebih lanjut cara mendesain perintah multimodal, lihat Mendesain perintah multimodal. Jika Anda mencari cara untuk menggunakan Gemini langsung dari aplikasi seluler dan web, lihat SDK klien Firebase AI Logic untuk aplikasi Swift, Android, Web, Flutter, dan Unity.

Batas endpoint API dan jendela konteks

Model Gemini 3 dan yang lebih baru standar menerima hingga 3.000 gambar dan PDF gabungan, 1.000 file audio, atau 10 video per permintaan di generateContent dan Interactions API (hingga 6.500 file multimodal gabungan jika file teks biasa disertakan). Endpoint Gemini 2.5 dan gemini-3.1-pro-preview-customtools yang tidak dimigrasikan menerapkan ukuran file lama, halaman PDF (1.000), dan batas jumlah URL HTTP atau HTTPS. Batas permintaan praktis juga bergantung pada endpoint API, sumber file, dan jendela konteks:

  • Batas URI Interactions API untuk file Cloud Storage: Permintaan Interactions API mendukung hingga 100 URI Cloud Storage (gs://) yang berbeda per permintaan interaksi model, termasuk URI yang diteruskan dari giliran percakapan sebelumnya melalui previous_interaction_id. Permintaan generateContent mendukung URI gs:// hingga batas item model.
  • Batas sumber file, bagian inline, dan payload permintaan: File individual yang direferensikan dari Cloud Storage tidak boleh melebihi 2 GiB dikurangi 500 KiB, dan file yang direferensikan dari URL HTTP atau HTTPS publik tidak boleh melebihi 15 MiB. Di generateContent dan streamGenerateContent, setiap lampiran inline (inline_data) tidak boleh melebihi 256 MB pada model Gemini 3 standar dan yang lebih baru, dan total payload permintaan HTTP atau gRPC yang dikompresi tidak boleh melebihi 500 MiB (encoding base64 menambahkan overhead ukuran sekitar 33%). Di Interactions API, payload permintaan HTTP yang dikompresi tidak boleh melebihi 256 MiB untuk permintaan sinkron atau streaming; jika service_tier ditetapkan ke deferred (yang mengharuskan background dan store ditetapkan ke true), permintaan yang tidak dikompresi tidak boleh melebihi 9,75 MiB.
  • Jendela konteks: Jumlah token gabungan dari semua input multimodal dan teks dalam permintaan tidak boleh melebihi batas token input model (1.048.576 token pada model Gemini 3 standar dan yang lebih baru).

Menambahkan video ke permintaan

Anda dapat menambahkan satu atau beberapa video dalam permintaan Anda ke Gemini dan video tersebut dapat menyertakan audio.

Video tunggal

Kode contoh di setiap tab berikut menunjukkan cara yang berbeda untuk mengidentifikasi konten dalam video. Contoh ini berfungsi dengan semua model multimodal Gemini.

Konsol

Untuk mengirim perintah multimodal menggunakan konsol Google Cloud , lakukan hal berikut:

  1. Di bagian Agent Platform pada konsol Google Cloud , buka halaman Agent Studio.

    Buka Agent Studio

  2. Klik Create prompt.

  3. Opsional: Konfigurasi model dan parameter:

    • Model: Pilih model.
  4. Opsional: Untuk mengonfigurasi parameter lanjutan, klik Advanced dan konfigurasikan sebagai berikut:

    Klik untuk meluaskan konfigurasi lanjutan

    • Top-K: Gunakan penggeser atau kotak teks untuk memasukkan nilai untuk top-K.

      Top-K mengubah cara model memilih token untuk output. Top-K 1 berarti token yang dipilih berikutnya adalah yang paling mungkin di antara semua token dalam kosakata model (juga disebut decoding greedy), sedangkan top-K 3 berarti token berikutnya dipilih di antara tiga token yang paling mungkin dengan menggunakan suhu.

      Untuk setiap langkah pemilihan token, token top-K dengan probabilitas tertinggi akan diambil sampelnya. Kemudian token akan difilter lebih lanjut berdasarkan top-P dengan token akhir yang dipilih menggunakan pengambilan sampel suhu.

      Tentukan nilai yang lebih rendah untuk respons acak yang lebih sedikit dan nilai yang lebih tinggi untuk respons acak yang lebih banyak.

    • Top-P: Gunakan penggeser atau kotak teks untuk memasukkan nilai untuk top-P. Token dipilih dari yang paling mungkin hingga yang paling tidak mungkin sampai jumlah probabilitasnya sama dengan nilai top-P. Untuk hasil yang paling sedikit variabelnya, tetapkan top-P ke 0.
    • Respons maks: Gunakan penggeser atau kotak teks untuk memasukkan nilai jumlah respons yang akan dihasilkan.
    • Streaming responses: Aktifkan untuk mencetak respons saat dibuat.
    • Nilai minimum filter keamanan: Pilih nilai minimum seberapa besar kemungkinan Anda melihat respons yang dapat berbahaya.
    • Enable Grounding: Grounding tidak didukung untuk perintah multimodal.
    • Region: Pilih region yang ingin Anda gunakan.
    • Suhu: Gunakan penggeser atau kotak teks untuk memasukkan nilai suhu.

          
      The temperature is used for sampling during response generation, which occurs when topP
      and topK are applied. Temperature controls the degree of randomness in token selection.
      Lower temperatures are good for prompts that require a less open-ended or creative response, while
      higher temperatures can lead to more diverse or creative results. A temperature of 0
      means that the highest probability tokens are always selected. In this case, responses for a given
      prompt are mostly deterministic, but a small amount of variation is still possible.
      
      

      If the model returns a response that's too generic, too short, or the model gives a fallback response, try increasing the temperature. If the model enters infinite generation, increasing the temperature to at least 0.1 may lead to improved results.

      1.0 is the recommended starting value for temperature. </li> <li>**Output token limit**: Use the slider or textbox to enter a value for the max output limit. Maximum number of tokens that can be generated in the response. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words.

      Specify a lower value for shorter responses and a higher value for potentially longer responses.

      </li> <li>**Add stop sequence**: Optional. Enter a stop sequence, which is a series of characters that includes spaces. If the model encounters a stop sequence, the response generation stops. The stop sequence isn't included in the response, and you can add up to five stop sequences.</li> </ul>

  5. Klik Sisipkan Media, lalu pilih sumber untuk file Anda.

    Upload

    Pilih file yang ingin diupload, lalu klik Buka.

    Melalui URL

    Masukkan URL file yang ingin Anda gunakan, lalu klik Sisipkan.

    YouTube

    Masukkan URL video YouTube yang ingin Anda gunakan, lalu klik Sisipkan.

    Anda dapat menggunakan video publik atau video yang dimiliki oleh akun yang Anda gunakan untuk login ke konsol Google Cloud .

    Cloud Storage

    Pilih bucket, lalu file dari bucket yang ingin Anda impor, dan klik Select.

    Google Drive

    1. Pilih akun dan berikan izin kepada Agent Studio untuk mengakses akun Anda saat pertama kali Anda memilih opsi ini. Anda dapat mengupload beberapa file yang memiliki ukuran total hingga 10 MB. Satu file tidak boleh melebihi 7 MB.
    2. Klik file yang ingin Anda tambahkan.
    3. Klik Pilih.

      Thumbnail file akan ditampilkan di panel Prompt. Jumlah total token juga ditampilkan. Jika data perintah Anda melebihi batas token, token akan dipotong dan tidak disertakan dalam pemrosesan data Anda.

  6. Masukkan perintah teks Anda di panel Prompt.

  7. Opsional: Untuk melihat Token ID to text dan Token IDs, klik tokens count di panel Prompt.

  8. Klik Kirim.

  9. Opsional: Untuk menyimpan perintah Anda ke My prompts, klik Save.

  10. Opsional: Untuk mendapatkan kode Python atau perintah curl untuk perintah Anda, klik Build with code > Get code.

Python

Instal

pip install --upgrade google-genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai
from google.genai.types import HttpOptions, Part

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        Part.from_uri(
            file_uri="gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
            mime_type="video/mp4",
        ),
        "What is in the video?",
    ],
)
print(response.text)
# Example response:
# The video shows several people surfing in an ocean with a coastline in the background. The camera ...

Go

Pelajari cara menginstal atau mengupdate Go.

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithMuteVideo shows how to generate text using a video with no sound as the input.
func generateWithMuteVideo(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "What is in the video?"},
			{FileData: &genai.FileData{
				FileURI:  "gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
				MIMEType: "video/mp4",
			}},
		},
			Role: genai.RoleUser},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, nil)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The video shows several surfers riding waves in an ocean setting. The waves are ...

	return nil
}

Java

Pelajari cara menginstal atau mengupdate Java.

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True


import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Part;

public class TextGenerationWithMuteVideo {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates text with mute video input
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      GenerateContentResponse response =
          client.models.generateContent(
              modelId,
              Content.fromParts(
                  Part.fromUri(
                      "gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
                      "video/mp4"),
                  Part.fromText("What is in this video?")),
              null);

      System.out.print(response.text());
      // Example response:
      // This video features **surfers in the ocean**.
      //
      // The main focus is on **one individual who catches and rides a wave**, executing various
      // turns and maneuvers as the wave breaks and dissipates into whitewater...
      return response.text();
    }
  }
}

Node.js

Instal

npm install @google/genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateText(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash-lite',
    contents: [
      {
        role: 'user',
        parts: [
          {
            fileData: {
              mimeType: 'video/mp4',
              fileUri:
                'gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4',
            },
          },
          {
            text: 'What is in the video?',
          },
        ],
      },
    ],
    config: {
      mediaResolution: 'MEDIA_RESOLUTION_LOW',
    },
  });

  console.log(response.text);

  // Example response:
  // The video shows several people surfing in an ocean with a coastline in the background. The camera ...

  return response.text;
}

REST

Setelah menyiapkan lingkungan, Anda dapat menggunakan REST untuk menguji perintah teks. Contoh berikut mengirimkan permintaan ke endpoint model penayang.

GenerateContent API

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Anda.
  • FILE_URI: URI atau URL file yang akan disertakan dalam perintah. Nilai yang dapat diterima mencakup hal berikut:
    • URI bucket Cloud Storage: Objek harus dapat dibaca secara publik atau berada dalam project Google Cloud yang sama dengan yang mengirim permintaan.
    • URL HTTP: URL file harus dapat dibaca secara publik dan tidak boleh melebihi 15 MiB per file. Model Gemini 3 dan yang lebih baru standar menerima hingga 3.000 gambar dan PDF yang digabungkan, 1.000 file audio, atau 10 video per permintaan (hingga total 6.500 file jika menyertakan file teks biasa). Endpoint Gemini 2.5 yang tidak dimigrasikan dan gemini-3.1-pro-preview-customtools membatasi URL HTTP atau HTTPS hingga 10 gambar, 1 file audio, atau 1 video per permintaan.
    • URL video YouTube:Video YouTube harus dimiliki oleh akun yang Anda gunakan untuk login ke konsol Google Cloud atau bersifat publik. Hanya satu URL video YouTube yang didukung per permintaan.

    Saat menentukan fileURI, Anda juga harus menentukan jenis media (mimeType) file. Jika Kontrol Layanan VPC diaktifkan, menentukan URL file media untuk fileURI tidak didukung.

    Jika Anda tidak memiliki file video di Cloud Storage, Anda dapat menggunakan file yang tersedia untuk umum berikut: gs://cloud-samples-data/video/animals.mp4 dengan jenis MIME video/mp4. Untuk melihat video ini, buka file MP4 contoh.

  • MIME_TYPE: Jenis media file yang ditentukan dalam kolom data atau fileUri. Nilai yang dapat diterima mencakup hal berikut:

    Klik untuk meluaskan jenis MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
  • TEXT: Petunjuk teks yang akan disertakan dalam perintah. Misalnya, What is in the video?

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

cat > request.json << 'EOF'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
EOF

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"

PowerShell

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

@'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content

Anda akan menerima respons JSON yang mirip dengan berikut ini.

Interactions API

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Anda.
  • FILE_URI: URI atau URL file yang akan disertakan dalam perintah. Nilai yang dapat diterima mencakup hal berikut:
    • URI bucket Cloud Storage: Objek harus dapat dibaca secara publik atau berada dalam project Google Cloud yang sama dengan yang mengirim permintaan.
    • URL HTTP: URL file harus dapat dibaca secara publik dan tidak boleh melebihi 15 MiB per file. Model Gemini 3 dan yang lebih baru standar menerima hingga 3.000 gambar dan PDF yang digabungkan, 1.000 file audio, atau 10 video per permintaan (hingga total 6.500 file jika menyertakan file teks biasa). Endpoint Gemini 2.5 yang tidak dimigrasikan dan gemini-3.1-pro-preview-customtools membatasi URL HTTP atau HTTPS hingga 10 gambar, 1 file audio, atau 1 video per permintaan.
    • URL video YouTube:Video YouTube harus dimiliki oleh akun yang Anda gunakan untuk login ke konsol Google Cloud atau bersifat publik. Hanya satu URL video YouTube yang didukung per permintaan.

    Saat menentukan fileURI, Anda juga harus menentukan jenis media (mimeType) file. Jika Kontrol Layanan VPC diaktifkan, menentukan URL file media untuk fileURI tidak didukung.

    Jika Anda tidak memiliki file video di Cloud Storage, Anda dapat menggunakan file yang tersedia untuk umum berikut: gs://cloud-samples-data/video/animals.mp4 dengan jenis MIME video/mp4. Untuk melihat video ini, buka file MP4 contoh.

  • MIME_TYPE: Jenis media file yang ditentukan dalam kolom data atau fileUri. Nilai yang dapat diterima mencakup hal berikut:

    Klik untuk meluaskan jenis MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
  • TEXT: Petunjuk teks yang akan disertakan dalam perintah. Misalnya, What is in the video?

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

cat > request.json << 'EOF'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
EOF

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions"

PowerShell

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

@'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" | Select-Object -Expand Content

Anda akan menerima respons JSON yang mirip dengan berikut ini.

Perhatikan hal berikut di URL untuk contoh ini:
  • Gunakan metode generateContent untuk meminta agar respons ditampilkan setelah dibuat sepenuhnya. Untuk mengurangi persepsi latensi bagi audiens manusia, lakukan streaming respons saat respons tersebut dibuat menggunakan metode streamGenerateContent.
  • ID model multimodal terletak di akhir URL sebelum metode (misalnya, gemini-3.5-flash). Contoh ini mungkin juga mendukung model lain.
  • Saat Anda menggunakan endpoint API regional (misalnya, us-central1), region dari URL endpoint menentukan tempat permintaan diproses. Setiap lokasi yang bertentangan di jalur resource akan diabaikan.

Video dengan audio

Berikut ini cara meringkas file video dengan audio dan menampilkan bab dengan stempel waktu. Contoh ini berfungsi dengan semua model multimodal Gemini yang mendukung video dengan audio.

Python

Instal

pip install --upgrade google-genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai
from google.genai.types import HttpOptions, Part

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        Part.from_uri(
            file_uri="gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
            mime_type="video/mp4",
        ),
        "What is in the video?",
    ],
)
print(response.text)
# Example response:
# The video shows several people surfing in an ocean with a coastline in the background. The camera ...

REST

Setelah menyiapkan lingkungan, Anda dapat menggunakan REST untuk menguji perintah teks. Contoh berikut mengirimkan permintaan ke endpoint model penayang.

GenerateContent API

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Anda.
  • FILE_URI: URI atau URL file yang akan disertakan dalam perintah. Nilai yang dapat diterima mencakup hal berikut:
    • URI bucket Cloud Storage: Objek harus dapat dibaca secara publik atau berada dalam project Google Cloud yang sama dengan yang mengirim permintaan.
    • URL HTTP: URL file harus dapat dibaca secara publik dan tidak boleh melebihi 15 MiB per file. Model Gemini 3 dan yang lebih baru standar menerima hingga 3.000 gambar dan PDF yang digabungkan, 1.000 file audio, atau 10 video per permintaan (hingga total 6.500 file jika menyertakan file teks biasa). Endpoint Gemini 2.5 yang tidak dimigrasikan dan gemini-3.1-pro-preview-customtools membatasi URL HTTP atau HTTPS hingga 10 gambar, 1 file audio, atau 1 video per permintaan.
    • URL video YouTube:Video YouTube harus dimiliki oleh akun yang Anda gunakan untuk login ke konsol Google Cloud atau bersifat publik. Hanya satu URL video YouTube yang didukung per permintaan.

    Saat menentukan fileURI, Anda juga harus menentukan jenis media (mimeType) file. Jika Kontrol Layanan VPC diaktifkan, menentukan URL file media untuk fileURI tidak didukung.

    Jika Anda tidak memiliki file video di Cloud Storage, Anda dapat menggunakan file yang tersedia untuk umum berikut: gs://cloud-samples-data/generative-ai/video/pixel8.mp4 dengan jenis MIME video/mp4. Untuk melihat video ini, buka file MP4 contoh.

  • MIME_TYPE: Jenis media file yang ditentukan dalam kolom data atau fileUri. Nilai yang dapat diterima mencakup hal berikut:

    Klik untuk meluaskan jenis MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
  • TEXT Petunjuk teks yang akan disertakan dalam perintah. Misalnya, Provide a description of the video. The description should also contain anything important which people say in the video.

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

cat > request.json << 'EOF'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
EOF

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent"

PowerShell

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

@'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent" | Select-Object -Expand Content

Anda akan menerima respons JSON yang mirip dengan berikut ini.

Interactions API

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Anda.
  • FILE_URI: URI atau URL file yang akan disertakan dalam perintah. Nilai yang dapat diterima mencakup hal berikut:
    • URI bucket Cloud Storage: Objek harus dapat dibaca secara publik atau berada dalam project Google Cloud yang sama dengan yang mengirim permintaan.
    • URL HTTP: URL file harus dapat dibaca secara publik dan tidak boleh melebihi 15 MiB per file. Model Gemini 3 dan yang lebih baru standar menerima hingga 3.000 gambar dan PDF yang digabungkan, 1.000 file audio, atau 10 video per permintaan (hingga total 6.500 file jika menyertakan file teks biasa). Endpoint Gemini 2.5 yang tidak dimigrasikan dan gemini-3.1-pro-preview-customtools membatasi URL HTTP atau HTTPS hingga 10 gambar, 1 file audio, atau 1 video per permintaan.
    • URL video YouTube:Video YouTube harus dimiliki oleh akun yang Anda gunakan untuk login ke konsol Google Cloud atau bersifat publik. Hanya satu URL video YouTube yang didukung per permintaan.

    Saat menentukan fileURI, Anda juga harus menentukan jenis media (mimeType) file. Jika Kontrol Layanan VPC diaktifkan, menentukan URL file media untuk fileURI tidak didukung.

    Jika Anda tidak memiliki file video di Cloud Storage, Anda dapat menggunakan file yang tersedia untuk umum berikut: gs://cloud-samples-data/generative-ai/video/pixel8.mp4 dengan jenis MIME video/mp4. Untuk melihat video ini, buka file MP4 contoh.

  • MIME_TYPE: Jenis media file yang ditentukan dalam kolom data atau fileUri. Nilai yang dapat diterima mencakup hal berikut:

    Klik untuk meluaskan jenis MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
  • TEXT Petunjuk teks yang akan disertakan dalam perintah. Misalnya, Provide a description of the video. The description should also contain anything important which people say in the video.

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

cat > request.json << 'EOF'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
EOF

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions"

PowerShell

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

@'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" | Select-Object -Expand Content

Anda akan menerima respons JSON yang mirip dengan berikut ini.

Perhatikan hal berikut di URL untuk contoh ini:
  • Gunakan metode generateContent untuk meminta agar respons ditampilkan setelah dibuat sepenuhnya. Untuk mengurangi persepsi latensi bagi audiens manusia, lakukan streaming respons saat respons tersebut dibuat menggunakan metode streamGenerateContent.
  • ID model multimodal terletak di akhir URL sebelum metode (misalnya, gemini-3.5-flash). Contoh ini mungkin juga mendukung model lain.
  • Saat Anda menggunakan endpoint API regional (misalnya, us-central1), region dari URL endpoint menentukan tempat permintaan diproses. Setiap lokasi yang bertentangan di jalur resource akan diabaikan.

Konsol

Untuk mengirim perintah multimodal menggunakan konsol Google Cloud , lakukan hal berikut:

  1. Di bagian Agent Platform pada konsol Google Cloud , buka halaman Agent Studio.

    Buka Agent Studio

  2. Klik Create prompt.

  3. Opsional: Konfigurasi model dan parameter:

    • Model: Pilih model.
  4. Opsional: Untuk mengonfigurasi parameter lanjutan, klik Advanced dan konfigurasikan sebagai berikut:

    Klik untuk meluaskan konfigurasi lanjutan

    • Top-K: Gunakan penggeser atau kotak teks untuk memasukkan nilai untuk top-K.

      Top-K mengubah cara model memilih token untuk output. Top-K 1 berarti token yang dipilih berikutnya adalah yang paling mungkin di antara semua token dalam kosakata model (juga disebut decoding greedy), sedangkan top-K 3 berarti token berikutnya dipilih di antara tiga token yang paling mungkin dengan menggunakan suhu.

      Untuk setiap langkah pemilihan token, token top-K dengan probabilitas tertinggi akan diambil sampelnya. Kemudian token akan difilter lebih lanjut berdasarkan top-P dengan token akhir yang dipilih menggunakan pengambilan sampel suhu.

      Tentukan nilai yang lebih rendah untuk respons acak yang lebih sedikit dan nilai yang lebih tinggi untuk respons acak yang lebih banyak.

    • Top-P: Gunakan penggeser atau kotak teks untuk memasukkan nilai untuk top-P. Token dipilih dari yang paling mungkin hingga yang paling tidak mungkin sampai jumlah probabilitasnya sama dengan nilai top-P. Untuk hasil yang paling sedikit variabelnya, tetapkan top-P ke 0.
    • Respons maks: Gunakan penggeser atau kotak teks untuk memasukkan nilai jumlah respons yang akan dihasilkan.
    • Streaming responses: Aktifkan untuk mencetak respons saat dibuat.
    • Nilai minimum filter keamanan: Pilih nilai minimum seberapa besar kemungkinan Anda melihat respons yang dapat berbahaya.
    • Enable Grounding: Grounding tidak didukung untuk perintah multimodal.
    • Region: Pilih region yang ingin Anda gunakan.
    • Suhu: Gunakan penggeser atau kotak teks untuk memasukkan nilai suhu.

          
      The temperature is used for sampling during response generation, which occurs when topP
      and topK are applied. Temperature controls the degree of randomness in token selection.
      Lower temperatures are good for prompts that require a less open-ended or creative response, while
      higher temperatures can lead to more diverse or creative results. A temperature of 0
      means that the highest probability tokens are always selected. In this case, responses for a given
      prompt are mostly deterministic, but a small amount of variation is still possible.
      
      

      If the model returns a response that's too generic, too short, or the model gives a fallback response, try increasing the temperature. If the model enters infinite generation, increasing the temperature to at least 0.1 may lead to improved results.

      1.0 is the recommended starting value for temperature. </li> <li>**Output token limit**: Use the slider or textbox to enter a value for the max output limit. Maximum number of tokens that can be generated in the response. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words.

      Specify a lower value for shorter responses and a higher value for potentially longer responses.

      </li> <li>**Add stop sequence**: Optional. Enter a stop sequence, which is a series of characters that includes spaces. If the model encounters a stop sequence, the response generation stops. The stop sequence isn't included in the response, and you can add up to five stop sequences.</li> </ul>

  5. Klik Sisipkan Media, lalu pilih sumber untuk file Anda.

    Upload

    Pilih file yang ingin diupload, lalu klik Buka.

    Melalui URL

    Masukkan URL file yang ingin Anda gunakan, lalu klik Sisipkan.

    YouTube

    Masukkan URL video YouTube yang ingin Anda gunakan, lalu klik Sisipkan.

    Anda dapat menggunakan video publik atau video yang dimiliki oleh akun yang Anda gunakan untuk login ke konsol Google Cloud .

    Cloud Storage

    Pilih bucket, lalu file dari bucket yang ingin Anda impor, dan klik Select.

    Google Drive

    1. Pilih akun dan berikan izin kepada Agent Studio untuk mengakses akun Anda saat pertama kali Anda memilih opsi ini. Anda dapat mengupload beberapa file yang memiliki ukuran total hingga 10 MB. Satu file tidak boleh melebihi 7 MB.
    2. Klik file yang ingin Anda tambahkan.
    3. Klik Pilih.

      Thumbnail file akan ditampilkan di panel Prompt. Jumlah total token juga ditampilkan. Jika data perintah Anda melebihi batas token, token akan dipotong dan tidak disertakan dalam pemrosesan data Anda.

  6. Masukkan perintah teks Anda di panel Prompt.

  7. Opsional: Untuk melihat Token ID to text dan Token IDs, klik tokens count di panel Prompt.

  8. Klik Kirim.

  9. Opsional: Untuk menyimpan perintah Anda ke My prompts, klik Save.

  10. Opsional: Untuk mendapatkan kode Python atau perintah curl untuk perintah Anda, klik Build with code > Get code.

Menyesuaikan pemrosesan video

Anda dapat menyesuaikan pemrosesan video di Gemini for Google Cloud API dengan menetapkan interval kliping atau memberikan pengambilan sampel kecepatan frame kustom.

Menetapkan interval kliping

Anda dapat membuat klip video dengan menentukan videoMetadata dengan offset awal dan akhir.

Menetapkan kecepatan frame kustom

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

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). Jika Anda ingin menangkap lebih banyak detail dalam visual yang berubah dengan cepat, pertimbangkan untuk menetapkan nilai FPS yang lebih tinggi.

Pemahaman video agentic

Pemahaman video agentic memungkinkan model menavigasi konten video secara dinamis, tanpa harus memproses setiap frame secara statis. Pemahaman video agentic menggunakan lebih sedikit token daripada pemrosesan statis dan dapat meningkatkan kualitas respons. Hal ini dapat menghasilkan biaya yang lebih rendah dan respons yang lebih cepat untuk workload video panjang.

Anda dapat menggunakan pemahaman video agentic dan pemrosesan statis untuk video yang berbeda dalam permintaan yang sama. Misalnya, jika Anda memiliki video panjang (seperti kuliah berdurasi satu jam) dan konten video pendek (seperti YouTube Shorts), Anda dapat menggunakan pemahaman video agentic pada video panjang untuk menargetkan informasi yang relevan secara kontekstual dan pemrosesan statis pada konten video pendek untuk presisi tingkat frame.

Konteks video harus dipertahankan di seluruh giliran dalam percakapan:

  • Interactions API: Secara default, interaksi stateful mempertahankan konteks video secara otomatis saat menggunakan previous_interaction_id. Untuk permintaan stateless (jika tidak menggunakan previous_interaction_id), responsnya menyertakan steps yang mengenkode konteks video; Anda harus meneruskan langkah-langkah ini ke giliran berikutnya untuk mempertahankan konteks.
  • GenerateContent API: Anda harus meneruskan histori percakapan lengkap (semua giliran contents sebelumnya) dalam setiap permintaan berikutnya untuk mempertahankan konteks.

Jika konteks video dihilangkan dalam giliran percakapan lanjutan, model tidak dapat menjawab pertanyaan tentang video tersebut tanpa memproses ulang video tersebut.

Model dan jenis file yang didukung

Pemahaman video agentic didukung dalam model berikut:

Klik untuk meluaskan model yang didukung

Anda dapat menggunakan sumber berikut saat menggunakan pemahaman video agentic:

  • URL YouTube
  • Cloud Storage URI
  • File video berenkode Base64 inline

Kapan harus menggunakan pemahaman video agentic

Gunakan pemahaman video agentic (media_processing = "AGENTIC") untuk workload berikut:

  • Tanya jawab dan penelusuran video panjang: Ajukan pertanyaan yang ditargetkan atau temukan peristiwa tertentu dalam kuliah, rapat, rekaman, atau tutorial video berdurasi satu jam tanpa melakukan tokenisasi pada setiap frame dalam resolusi penuh.
  • Pemeriksaan visual yang mendetail: Memperbesar stempel waktu atau detail visual tertentu (seperti membaca teks kecil di layar, slide, atau perubahan papan skor) dalam video yang lebih panjang.
  • Perbandingan multi-video: Bandingkan beberapa video dalam satu permintaan. Anda dapat menggunakan mode pemrosesan yang berbeda untuk setiap video dalam permintaan yang sama.
  • Agen yang didukung video: Bangun agen yang melakukan penalaran atas konten video dengan dukungan percakapan multi-turn. Konteks video dipertahankan di seluruh giliran tanpa pemrosesan ulang.
  • Pengoptimalan biaya untuk workload video panjang: Kurangi konsumsi token untuk aplikasi video panjang yang hanya sebagian segmennya relevan dengan perintah.

Pertahankan pemrosesan statis default (media_processing = "STATIC") jika:

  • Memproses klip pendek: Untuk video pendek, pemrosesan statis menghindari overhead navigasi alat multi-langkah dan biasanya menggunakan lebih sedikit token dengan latensi yang lebih rendah.
  • Pemrosesan video lengkap yang seragam: Workload Anda memerlukan analisis frame demi frame yang seragam di seluruh klip, bukan pemeriksaan yang ditargetkan pada segmen tertentu.

Menggunakan pemahaman video agentic

Anda dapat mengaktifkan pemahaman video agentic dengan menetapkan "processing": "agentic" di Interactions API atau media_processing = "AGENTIC" di GenerateContent API:

Python

GenerateContent API

from google import genai
from google.genai import types

client = genai.Client()

# Example: Controlling media_processing explicitly
video_part = types.Part(
  file_data=types.FileData(
      file_uri="gs://my-bucket-name/sports_clip.mp4",
      mime_type="video/mp4",
  ),
  media_processing="agentic" # Options: "agentic", "static"
)

response = client.models.generate_content(
  model="gemini-3.7-flash",
  contents=[
      video_part,
      "Analyze the player's footwork right before the shot."
  ]
)
print(response.text)

Interactions API

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Example: Controlling video processing explicitly
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": "gs://my-bucket-name/sports_clip.mp4",
            "mime_type": "video/mp4",
            "processing": "agentic",  # Options: "agentic", "static"
        },
        {
            "type": "text",
            "text": "Analyze the player's footwork right before the shot.",
        },
    ],
    generation_config={
        "thinking_level": "medium",
    },
)
print(interaction.output_text)

REST

GenerateContent API

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

cat > request.json << 'EOF'
{
  "contents": [
    {
      "role": "USER",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://my-bucket/lecture.mp4"
          },
          "mediaProcessing": "AGENTIC"
        },
        {
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingLevel": "MEDIUM"
  }
}
EOF

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.7-flash:generateContent"

PowerShell

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

@'
{
  "contents": [
    {
      "role": "USER",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://my-bucket/lecture.mp4"
          },
          "mediaProcessing": "AGENTIC"
        },
        {
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingLevel": "MEDIUM"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Kemudian jalankan perintah berikut untuk mengirim permintaan REST Anda:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.7-flash:generateContent" | Select-Object -Expand Content

Interactions API

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

cat > request.json << 'EOF'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "mime_type": "video/mp4",
          "uri": "gs://my-bucket/lecture.mp4",
          "processing": "agentic"
        },
        {
          "type": "text",
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generation_config": {
    "thinking_level": "medium"
  }
}
EOF

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions"

PowerShell

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

@'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "mime_type": "video/mp4",
          "uri": "gs://my-bucket/lecture.mp4",
          "processing": "agentic"
        },
        {
          "type": "text",
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generation_config": {
    "thinking_level": "medium"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Kemudian jalankan perintah berikut untuk mengirim permintaan REST Anda:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" | Select-Object -Expand Content

Pemahaman video agentic ditetapkan ke STATIC atau dinonaktifkan secara default untuk semua model yang didukung.

Menyesuaikan resolusi media

Anda dapat menyesuaikan MediaResolution untuk memproses video dengan lebih sedikit token.

Menetapkan parameter model opsional

Setiap model memiliki serangkaian parameter opsional yang dapat Anda tetapkan. Untuk mengetahui informasi selengkapnya, lihat Parameter pembuatan konten.

Tokenisasi video

Dengan Gemini 3, tokenisasi video menggunakan panjang urutan variabel, yang menggantikan metode Pan and Scan yang digunakan dalam model sebelumnya untuk kualitas dan latensi yang lebih baik.

Anda dapat menentukan resolusi media untuk input video, yang memengaruhi cara video ditokenisasi dan jumlah token yang digunakan untuk setiap video. Anda dapat menetapkan media_resolution di generationConfig untuk diterapkan ke semua media dalam permintaan, atau menetapkannya untuk setiap bagian media, yang akan menggantikan setelan tingkat teratas. Resolusi default untuk video adalah 70 token per frame.

Resolusi berikut tersedia untuk model Gemini 3:

  • MEDIA_RESOLUTION_HIGH: 280 token per frame
  • MEDIA_RESOLUTION_MEDIUM: 70 token per frame
  • MEDIA_RESOLUTION_LOW: 70 token per frame
  • MEDIA_RESOLUTION_UNSPECIFIED: 70 token per frame (default)

Untuk model sebelum Gemini 3, setiap frame ditokenisasi dengan 258 token per frame untuk resolusi default, atau 66 token per frame untuk resolusi rendah.

Contoh kode ini menunjukkan cara menyesuaikan media_resolution:

GenerateContent API

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3.1-pro-preview",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_HIGH
          ),
      ),
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4",
              mime_type="video/mp4",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_LOW
          ),
      ),
      "When does the image appear in the video? What is the context?",
  ],
)
print(response.text)

Interactions API

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "image",
            "uri": "gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
            "mime_type": "image/png",
            "resolution": "high",  # Options: "low", "medium", "high", "ultra_high"
        },
        {
            "type": "video",
            "uri": "gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4",
            "mime_type": "video/mp4",
            "resolution": "low",  # Options: "low", "medium", "high", "ultra_high"
        },
        {
            "type": "text",
            "text": "When does the image appear in the video? What is the context?",
        },
    ],
)
print(interaction.output_text)

Praktik terbaik

Saat menggunakan video, gunakan praktik terbaik dan informasi berikut untuk mendapatkan hasil terbaik:

  • Jika perintah Anda berisi satu video, tempatkan video sebelum perintah teks.
  • Jika Anda memerlukan pelokalan stempel waktu dalam video dengan audio, minta model untuk membuat stempel waktu yang mengikuti format seperti yang dijelaskan dalam "Format stempel waktu".

Untuk model Gemini 3, pertimbangkan juga hal berikut:

  • Gunakan frekuensi sampling Frame Per Detik (FPS) yang lebih tinggi untuk video yang memerlukan analisis temporal terperinci, seperti pemahaman tindakan cepat atau pelacakan gerakan berkecepatan tinggi.

Batasan

Meskipun model multimodal Gemini sangat efektif dalam banyak kasus penggunaan multimodal, penting untuk memahami batasan model tersebut:

  • Moderasi konten: Model menolak memberikan jawaban pada video yang melanggar kebijakan keamanan kami.
  • Pengenalan suara non-ucapan: Model yang mendukung audio mungkin membuat kesalahan dalam mengenali suara yang bukan ucapan.

Detail teknis tentang video

  • Pemrosesan File API: Saat menggunakan File API, video diambil sampelnya pada 1 frame per detik (FPS) dan audio diproses pada 1 Kbps (saluran tunggal). Stempel waktu ditambahkan setiap detik.

    • Tarif ini dapat berubah di masa mendatang untuk peningkatan inferensi.
  • Format stempel waktu: Saat merujuk ke momen tertentu dalam video dalam perintah Anda, format stempel waktu bergantung pada frekuensi sampling frame per detik (FPS) video Anda:

    • Untuk frekuensi sampling pada 1 FPS atau lebih rendah: Gunakan format MM:SS, dengan dua digit pertama mewakili menit dan dua digit terakhir mewakili detik. Jika Anda memiliki offset yang lebih besar dari 1 jam, gunakan format H:MM:SS.

    • Untuk frekuensi sampling di atas 1 FPS: Gunakan format MM:SS.sss, atau, jika Anda memiliki offset yang lebih besar dari 1 jam, gunakan format H:MM:SS.sss, yang dijelaskan sebagai berikut:

      • Digit pertama menunjukkan jam.
      • Dua digit kedua menunjukkan menit.
      • Dua digit ketiga mewakili detik.
      • Tiga digit terakhir menunjukkan subdetik.
  • Praktik terbaik:

    • Gunakan hanya satu video per permintaan perintah untuk mendapatkan hasil yang optimal.

    • Jika menggabungkan teks dan satu video, tempatkan perintah teks setelah bagian video dalam array contents.

    • Perlu diketahui bahwa urutan tindakan cepat mungkin kehilangan detail karena frekuensi sampling 1 FPS. Pertimbangkan untuk memperlambat klip tersebut jika perlu.

Langkah berikutnya