Video anlama

Video üretimi hakkında bilgi edinmek için Gemini Omni Flash rehberine bakın.

Gemini modelleri videoları işleyebilir. Bu sayede, geçmişte alana özgü modeller gerektiren birçok ileri düzey geliştirici kullanım alanı mümkün hale gelir. Gemini'ın bazı görme özellikleri arasında videoları açıklama, segmentlere ayırma ve videolardan bilgi ayıklama, video içeriğiyle ilgili soruları yanıtlama ve videodaki belirli zaman damgalarına başvurma yer alır.

Gemini'a giriş olarak videoları aşağıdaki şekillerde sağlayabilirsiniz:

Giriş yöntemi Maks. boyut Önerilen kullanım alanı
File API 20 GB (ücretli) / 2 GB (ücretsiz) Büyük dosyalar (100 MB+), uzun videolar (10 dk+), yeniden kullanılabilir dosyalar.
Cloud Storage kaydı 2 GB (dosya başına, depolama alanı sınırı yok) Büyük dosyalar (100 MB'tan büyük), uzun videolar (10 dakikadan uzun), kalıcı ve yeniden kullanılabilir dosyalar.
Satır içi veriler < 100MB Küçük dosyalar (<100 MB), kısa süre (<1 dakika), tek seferlik girişler.
YouTube URL'leri Yok Herkese açık YouTube videoları

Not: File API, özellikle 100 MB'tan büyük dosyalar için veya dosyayı birden fazla istekte yeniden kullanmak istediğinizde çoğu kullanım alanı için önerilir.

Harici URL'leri veya Google Cloud'da depolanan dosyaları kullanma gibi diğer dosya giriş yöntemleri hakkında bilgi edinmek için Dosya giriş yöntemleri kılavuzuna bakın.

Video dosyası yükleme

Aşağıdaki kod, örnek bir video indirir, Files API'yi kullanarak videoyu yükler, işlenmesini bekler ve ardından videoyu özetlemek için yüklenen dosya referansını kullanır.

Python

from google import genai
import time

client = genai.Client()

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

while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "video", "uri": myfile.uri, "mime_type": myfile.mime_type},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
    ]
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } 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" },
  });

  let getFile = await ai.files.get({ name: myfile.name });
  while (getFile.state === 'PROCESSING') {
      getFile = await ai.files.get({ name: myfile.name });
      console.log(`current file status: ${getFile.state}`);
      console.log('File is still processing, retrying in 5 seconds');

      await new Promise((resolve) => {
          setTimeout(resolve, 5000);
      });
  }
  if (getFile.state === 'FAILED') {
      throw new Error('File processing failed.');
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "video", uri: myfile.uri, mime_type: myfile.mimeType },
      { type: "text", text: "Summarize this video. Then create a quiz with an answer key based on the information in this video." }
    ],
  });
  console.log(interaction.output_text);
}

await main();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.FileState;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File myfile =
    client.files.upload(
        "path/to/sample.mp4", UploadFileConfig.builder().mimeType("video/mp4").build());

while (!myfile.state().isPresent()
    || myfile.state().get().knownEnum() != FileState.Known.ACTIVE) {
  System.out.println("Processing video...");
  Thread.sleep(5000);
  myfile = client.files.get(myfile.name().get(), null);
}

Content videoContent =
    VideoContent.builder()
        .uri(myfile.uri().get())
        .mimeType(VideoContentMimeType.of(myfile.mimeType().get()))
        .build();
Content textContent =
    TextContent.builder()
        .text(
            "Summarize this video. Then create a quiz with an answer key based on the information in this video.")
        .build();

List<Content> contents = Arrays.asList(videoContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    myfile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    })
    if err != nil {
        log.Fatal(err)
    }

    for myfile.State != genai.FileStateActive {
        fmt.Println("Processing video...")
        time.Sleep(5 * time.Second)
        myfile, err = client.Files.Get(ctx, myfile.Name, nil)
        if err != nil {
            log.Fatal(err)
        }
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI:      genai.Ptr(myfile.URI),
            MimeType: interactions.VideoContentMimeType(myfile.MIMEType).ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

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

tmp_header_file=upload-header.tmp

echo "Starting file upload..."
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D ${tmp_header_file} \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

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

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

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

# Polling loop
echo "Waiting for file to be processed..."
while true; do
  curl -s "https://generativelanguage.googleapis.com/v1beta/${file_name}" \
    -H "x-goog-api-key: $GEMINI_API_KEY" > file_status.json
  state=$(jq -r ".state" file_status.json)
  echo "Current state: $state"
  if [ "$state" == "ACTIVE" ]; then
    break
  elif [ "$state" == "FAILED" ]; then
    echo "File processing failed."
    exit 1
  fi
  sleep 5
done

echo "Generating content from video..."
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "video", "uri": "'${file_uri}'", "mime_type": "'${MIME_TYPE}'"},
        {"type": "text", "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 ".steps[].content[0].text" response.json

Token verimliliğini ve performansı optimize etmek için Agentic video işleme'yi kullanabilirsiniz.

Toplam istek boyutu (dosya, metin istemi, sistem talimatları vb. dahil) 20 MB'tan büyükse, video süresi önemliyse veya aynı videoyu birden fazla istemde kullanmak istiyorsanız her zaman Files API'yi kullanın. File API, video dosyası biçimlerini doğrudan kabul eder.

Medya dosyalarıyla çalışma hakkında daha fazla bilgi edinmek için Files API'ye bakın.

Video verilerini satır içi olarak iletme

File API'yi kullanarak video dosyası yüklemek yerine daha küçük videoları doğrudan isteğe iletebilirsiniz. Bu yöntem, toplam istek boyutu 20 MB'tan az olan kısa videolar için uygundur.

Satır içi video verileri sağlama örneğini aşağıda bulabilirsiniz:

Python

from google import genai
import base64

video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "data": base64.b64encode(video_bytes).decode('utf-8'),
            "mime_type": "video/mp4"
        }
    ]
)
print(interaction.output_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 interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      data: base64VideoFile,
      mime_type: "video/mp4",
    }
  ],
});
console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

String videoFileName = "/path/to/your/video.mp4";
byte[] videoBytes = Files.readAllBytes(Paths.get(videoFileName));
String base64Video = Base64.getEncoder().encodeToString(videoBytes);

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .data(base64Video)
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    videoFileName := "/path/to/your/video.mp4"
    videoBytes, err := os.ReadFile(videoFileName)
    if err != nil {
        log.Fatal(err)
    }
    base64Video := base64.StdEncoding.EncodeToString(videoBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            Data:     genai.Ptr(base64Video),
            MimeType: interactions.VideoContentMimeTypeVideoMp4.ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

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

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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'",
          "mime_type": "video/mp4"
        }
      ]
    }' 2> /dev/null

YouTube URL'lerini iletme

YouTube URL'lerini, isteğinizin bir parçası olarak doğrudan Gemini API'ye aşağıdaki şekilde iletebilirsiniz:

Python

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
    ]
)
print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      uri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    }
  ],
});
console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .uri("https://www.youtube.com/watch?v=9hE5-98ZeCg")
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            URI: genai.Ptr("https://www.youtube.com/watch?v=9hE5-98ZeCg"),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
      ]
    }' 2> /dev/null

Sınırlamalar:

  • Ücretsiz katmanda, günde 8 saatten fazla YouTube videosu yükleyemezsiniz.
  • Ücretli katmanda video uzunluğuna göre bir sınır yoktur.
  • Gemini 2.5'ten önceki modellerde, istek başına yalnızca 1 video yükleyebilirsiniz. Gemini 2.5 ve sonraki modellerde istek başına en fazla 10 video yükleyebilirsiniz.
  • Yalnızca herkese açık videolar yükleyebilirsiniz (gizli veya liste dışı videolar yüklenemez).

Ajan tabanlı video anlama

Varsayılan olarak, video girişleri Gemini 4 dahil tüm modellerde statik işlemeyi (1 FPS'de kare çıkarma) kullanır. Gemini 4 Argon, 3.8 Flash, 3.6 Flash ve 3.5 Flash Lite modelleri de agentic video understanding özelliğini destekler. Bu özellik, modelin video zaman çizelgesini dinamik olarak keşfettiği, transkriptleri seçici bir şekilde incelediği ve isteme göre kare hızlarını ve çözünürlüğü anında uyarlanabilir şekilde ayarladığı bir etkinleştirme modudur.

Mod Açıklama Desteklenen modeller
Statik (varsayılan) Kareleri sabit bir hızda (1 FPS) çıkarır ve tek bir geçişte bağlama yerleştirir. Gemini 4 dahil olmak üzere tüm Gemini modellerinde varsayılan olarak etkindir. Tüm Gemini modelleri
Temsilci tabanlı çözümler Model, video zaman çizelgesinde dinamik olarak gezinir ve isteme göre yalnızca ihtiyaç duyduğu içeriği yükler. Uzun içeriklerde% 88'e kadar daha fazla jeton verimliliği ve yaklaşık% 7 daha yüksek kalite. Gemini 4 Argon, 3.8 Flash, 3.6 Flash, 3.5 Flash Lite

İşleme modu seçme

Videonuzun uzunluğuna ve sorgu türüne uygun işleme modunu seçin:

  • Statik (varsayılan): Kısa klipler (5 dakikadan kısa), kaydın tamamının alakalı olduğu geniş kapsamlı tam video özetleri, gecikmeye duyarlı sorgular veya klibin tamamında kare düzeyinde hassasiyet için en uygun seçenektir. Kısa videolarda veya videonun büyük bir kısmının incelenmesini gerektiren geniş kapsamlı istemlerde, statik işleme, zaman çizelgesinde gezinmenin neden olduğu ek düşünme jetonlarını (total_thought_tokens) ve araç çağrısı gidiş dönüşlerini (total_tool_use_tokens) önler.
  • Etkileşimli: Uzun videolar (5-10 dakikadan uzun), samanlıkta iğne arama veya belirli anları ya da konuları hedefleyen sorgular için en iyisidir. Model, önce transkriptleri inceler ve yalnızca alakalı görsel segmentleri isteğe bağlı olarak yükler. Böylece, bağlam penceresini doldurmadan video giriş jetonu kullanımını% 88'e kadar azaltır.

Not: Temsilci tabanlı işlemenin daha uzun sürdüğü uzun videolar veya karmaşık istemler için akış (stream=True) veya arka planda yürütme (background=True) kullanın. Bu sayede bağlantı etkin kalır, ara akıl yürütme adımları gösterilir ve bağlantı veya kimlik doğrulama zaman aşımı önlenir.

İşleme modunu ayarlama

Temsilci tabanlı video yorumlama özelliğini kullanmak için input dizisindeki video bölümünde "processing": "agentic" değerini ayarlayın.

Model, zaman çizelgesinde gezinmek için birden fazla inceleme geçişi yaptığından, uzun videolarda yapay zeka destekli video işleme daha uzun sürebilir. Ağ bağlantısı kesilirse ilerlemenin kaybolmasını önlemek için bu örnekte, görevi sunucuda eşzamansız olarak çalıştırmak üzere background=True kullanılır. Ayrıca, background parametresini atlayarak istekleri arka planda yürütme olmadan senkron olarak da çalıştırabilirsiniz. Bu yöntem, daha kısa videolar için uygundur.

Sorgulama, sonuçları alma ve arka plan görevlerini yönetme hakkında ayrıntılı bilgi için arka planda yürütme kılavuzuna bakın.

Python

import time
from google import genai

client = genai.Client()

# Upload a long video
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)

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": "agentic"
        },
        {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

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

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

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: "agentic"
    },
    { type: "text", text: "What are the three main arguments presented?" }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

Not: Temsilci tabanlı işlemenin kullanıldığını doğrulamak için interaction.steps öğesini inceleyin. processing_call ve processing_result simgelerinin varlığı, modelin videoda dinamik olarak gezindiğini gösterir.

Müdahale adımları

Temsilci tabanlı işleme, steps dizisine iki yeni adım türü ekler:

  • processing_call: Model, id ile tanımlanan bir video segmenti veya ses transkripti istedi.
  • processing_result: Bu yüklemenin sonucu, call_id ile bağlantılıdır.

Bunlar, thought adımlarıyla (özetler etkinleştirildiğinde) dönüşümlü olarak gösterilir ve son model_output adımından önce gelir. Kullanıcı arayüzünüzde ilerleme izi göstermek için kullanılabilir ancak yanıt gerektirmez.

Aşağıdaki örnekte, araya yerleştirilmiş işleme adımlarıyla birlikte yanıt yükü gösterilmektedir:

{
  "steps": [
    {
      "type": "thought",
      "signature": "sig_thought_1",
      "summary": [
        {
          "type": "text",
          "text": "Inspecting transcript for key discussion topics..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_01",
      "signature": "sig_call_01"
    },
    {
      "type": "processing_result",
      "call_id": "call_01",
      "signature": "sig_result_01"
    },
    {
      "type": "thought",
      "signature": "sig_thought_2",
      "summary": [
        {
          "type": "text",
          "text": "Loading visual frames to verify slide content..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_02",
      "signature": "sig_call_02"
    },
    {
      "type": "processing_result",
      "call_id": "call_02",
      "signature": "sig_result_02"
    },
    {
      "type": "thought",
      "signature": "sig_thought_3",
      "summary": [
        {
          "type": "text",
          "text": "Synthesizing answer from gathered evidence..."
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The three main arguments presented in the lecture are..."
        }
      ]
    }
  ]
}

Videolarda farklı işleme modlarını kullanma

Aynı istekteki her video için farklı işleme modları ayarlayın:

Python

import time
from google import genai

client = genai.Client()

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

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": lecture.uri,
            "mime_type": lecture.mime_type,
            "processing": "agentic"  # Use agentic video understanding
        },
        {
            "type": "video",
            "uri": experiment.uri,
            "mime_type": experiment.mime_type,
            "processing": "static"  # Use static processing
        },
        {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_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" }
});

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: lecture.uri,
      mime_type: lecture.mimeType,
      processing: "agentic" // Use agentic video understanding
    },
    {
      type: "video",
      uri: experiment.uri,
      mime_type: experiment.mimeType,
      processing: "static" // Use static processing
    },
    { type: "text", text: "Compare the lecture content with the experiment results." }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${lecture_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {
        "type": "video",
        "uri": "'${experiment_uri}'",
        "mime_type": "video/mp4",
        "processing": "static"
      },
      {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

Çok adımlı video görüşmeleri

Video bağlamı, görüşme boyunca korunur. Temsilci tabanlı işleme kullanırken:

  • Durumlu mod (previous_interaction_id kullanılarak): Sunucu, video bağlamını korur. Ek işlem yapılması gerekmez.
  • Durum bilgisiz mod (step_list kullanılarak): Durum bilgisiz modda yanıt, video bağlamını kodlayan processing_call ve processing_result adımlarını içerir. Video bağlamını korumak için yanıtın tüm adımlarını bir sonraki isteğinizin step_list bölümüne eklemeniz gerekir. Bu parametrelerin atlanması şu anda API hatasına neden olmasa da video bağlamı kaybolur ve takip sorularına verilen yanıtların kalitesi önemli ölçüde düşer. Sonraki isteklerde gönderilen döndürülen adımların giriş jetonu sayılarına katkıda bulunduğunu unutmayın.

İçerikteki zaman damgalarına bakın.

MM:SS biçimindeki zaman damgalarını kullanarak videodaki belirli zaman noktaları hakkında soru sorabilirsiniz.

Python

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

JavaScript

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

Java

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

Go

prompt := "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?"

Videodan ayrıntılı analizler çıkarma

Gemini modelleri, hem ses hem de görsel akışlardaki bilgileri işleyerek video içeriklerini anlamak için güçlü özellikler sunar. Bu sayede, videoda neler olduğuna dair açıklamalar oluşturma ve içeriğiyle ilgili soruları yanıtlama da dahil olmak üzere zengin bir ayrıntı kümesi çıkarabilirsiniz.

Görsel açıklamalar için model, videoyu saniyede 1 kare (FPS) hızında örnekler. Bu varsayılan örnekleme hızı çoğu içerik için uygundur ancak hızlı hareketlerin veya hızlı sahne değişikliklerinin olduğu videolardaki ayrıntıları kaçırabileceğini unutmayın.

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.";

Java

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

Go

prompt := "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."

Video işlemeyi özelleştirme

Kırpma aralıkları ayarlayarak veya özel kare hızı örneklemesi sağlayarak Gemini API'de video işlemeyi özelleştirebilirsiniz. Bu özelleştirme seçenekleri yalnızca video "static" modunda işlenirken desteklenir.

Kırpma aralıklarını ayarlama

processing yapılandırma nesnesinde start_offset ve end_offset değerlerini belirterek videoyu kırpabilirsiniz.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "start_offset": 1200,
                "end_offset": 1500,
            },
        },
        {"type": "text", "text": "Summarize this section of the video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        start_offset: 1200,
        end_offset: 1500,
      },
    },
    { type: "text", text: "Summarize this section of the video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "start_offset": 1200,
          "end_offset": 1500
        }
      },
      {"type": "text", "text": "Summarize this section of the video."}
    ]
  }' 2> /dev/null

Özel kare hızı ayarlama

processing yapılandırma nesnesinde bir fps bağımsız değişkeni ileterek özel kare hızı örneklemesi ayarlayabilirsiniz.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "fps": 0.5,  # Sample 1 frame every 2 seconds
            },
        },
        {"type": "text", "text": "Describe the scene changes in this video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        fps: 0.5, // Sample 1 frame every 2 seconds
      },
    },
    { type: "text", text: "Describe the scene changes in this video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "fps": 0.5
        }
      },
      {"type": "text", "text": "Describe the scene changes in this video."}
    ]
  }' 2> /dev/null

Desteklenen video biçimleri

Gemini aşağıdaki video biçimi MIME türlerini destekler:

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

Videolarla ilgili teknik ayrıntılar

  • Desteklenen modeller ve bağlam: Tüm Gemini modelleri video verilerini işleyebilir.
    • 1 milyon bağlam penceresine sahip modeller, varsayılan olarak 3 saate kadar (düşük medya çözünürlüğünde) veya yüksek medya çözünürlüğünde 1 saate kadar videoları işleyebilir.
  • İşleme modları: Gemini 4 Argon, 3.8 Flash, 3.6 Flash, 3.5 Flash Lite ve sonraki modeller iki video işleme modunu destekler:
    • Statik: Kareler 1 FPS hızında çıkarılır ve bağlama yerleştirilir (tüm modeller için varsayılan). Ses, 1 Kb/sn (tek kanal) hızında işlenir. Zaman damgaları her saniye eklenir. Kısa klipler veya her karenin önemli olduğu durumlar (ör. kare kare inceleme) için idealdir. Hızlı aksiyon sahnelerinde 1 FPS örnekleme hızı nedeniyle ayrıntı kaybı yaşanabileceğini unutmayın.
    • Temsilci: Model, videoda dinamik olarak gezinir ve transkripti, kareleri ve/veya sesi isteğe bağlı olarak yükler. Bu sayede uzun içerikler için %88'e kadar daha az jeton kullanılır. Ancak gezinme, dahili akıl yürütme ve araç gidiş dönüşleri nedeniyle kısa kliplerde (<5 dakika) veya geniş sorgularda ilk jeton süresini (TTFT) ve toplam jeton kullanımını artırabilir. Jeton maliyetlerini ve yanıt kalitesini optimize etmek için uzun videolar ve hedeflenen sorgular için en uygun seçenektir. Gemini 4 Argon, 3.8 Flash, 3.6 Flash ve 3.5 Flash Lite'ta desteklenir. Ayrıntılar için Temsilci tabanlı video yorumlama bölümüne bakın.
  • Jeton hesaplama (statik mod): Videonun her saniyesi aşağıdaki şekilde jetonlaştırılır:
    • Tek tek kareler (1 FPS'de örneklenmiş):
      • media_resolution düşük olarak ayarlanırsa kareler, kare başına 66 jeton olacak şekilde jetonlaştırılır.
      • Aksi takdirde kareler, kare başına 258 jeton olacak şekilde parçalara ayrılır.
    • Ses: Saniyede 32 jeton.
    • Meta veriler de dahil edilir.
    • Toplam: Varsayılan (düşük) medya çözünürlüğünde saniyede yaklaşık 100 jeton veya yüksek medya çözünürlüğünde saniyede yaklaşık 300 jeton.
  • Jeton hesaplama (temsilci modu): Jeton kullanımı, içeriğin karmaşıklığına ve modelin gezinme stratejisine göre değişir. Video keşfi sırasında oluşturulan gezinme muhakemesi jetonları düşünce jetonları (total_thought_tokens) olarak kabul edilirken isteğe bağlı olarak yüklenen kareler, ses ve transkriptler araç kullanımı jetonları (total_tool_use_tokens) olarak kabul edilir. Model, isteme yanıt vermek için yalnızca transkripti ve/veya kareleri ve/veya sesi yüklediğinden, uzun içeriklerdeki statik işleme kıyasla genellikle% 88'e kadar daha az toplam jeton kullanılır (bkz. jeton kılavuzu).
  • Medya çözünürlüğü: Gemini 3, media_resolution parametresiyle çok formatlı görüntü işleme üzerinde ayrıntılı kontrol sağlar. media_resolution parametresi, giriş resmi veya video karesi başına ayrılan maksimum jeton sayısını belirler. Daha yüksek çözünürlükler, modelin küçük metinleri okuma veya küçük ayrıntıları tanımlama becerisini artırır ancak jeton kullanımını ve gecikmeyi de artırır. media_resolution ve processing parametreleri bağımsızdır: İkisini de aynı video girişinde ayarlayabilirsiniz.

Jeton hesaplamaları hakkında daha fazla bilgi için jetonlar kılavuzuna bakın.

  • Zaman damgası biçimi: İsteminizde videodaki belirli anlara atıfta bulunurken MM:SS biçimini kullanın (ör. 1 dakika 15 saniye için 01:15).
  • İstem yerleşimi: Metin ve tek bir videoyu birleştiriyorsanız metin istemini input dizisindeki video bölümünden sonra yerleştirin.
  • Uzun istekler için zaman aşımları: Uzun işlem süresi veya karmaşık çok adımlı akıl yürütme gerektiren videolar için akış (stream=True) ya da arka planda yürütme (background=True) kullanın. Yüksek talep nedeniyle arka uçta yeniden denemeler yapılan eşzamanlı ve akış içermeyen istekler, bağlantı veya kimlik doğrulama jetonu geçerlilik sürelerini aşabilir. Bu durum, beklenmedik 401 Unauthorized veya zaman aşımı hatalarına neden olabilir. Yayın, bağlantıyı etkin tutar ve ara muhakeme ile araç çağrısı ilerleme durumunu gösterir.

Sırada ne var?

  • Medya çözünürlüğü: Kalite ve jeton kullanımı arasında denge kurmak için video karelerinin çözünürlüğünü kontrol edin.
  • Token'lar: Video içeriğinin hem statik hem de yapay zeka destekli işleme modlarında nasıl token'lara dönüştürüldüğünü anlayın.
  • Arka planda yürütme: Bağlantı zaman aşımlarını önlemek için uzun süren video anlama görevlerini eşzamansız olarak çalıştırın.
  • Sistem talimatları: Sistem talimatları, modelin davranışını özel ihtiyaçlarınıza ve kullanım alanlarınıza göre yönlendirmenizi sağlar.
  • Files API: Gemini ile kullanılacak dosyaları yükleme ve yönetme hakkında daha fazla bilgi edinin.
  • Dosya istemi stratejileri: Gemini API, çok formatlı istem olarak da bilinen metin, resim, ses ve video verileriyle istem oluşturmayı destekler.
  • Güvenlik kılavuzu: Üretken yapay zeka modelleri bazen yanlış, taraflı veya rahatsız edici gibi beklenmedik çıktılar üretebilir. Bu tür çıkışların neden olabileceği zarar riskini sınırlamak için son işleme ve uzman değerlendirmesi çok önemlidir.