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 dk), tek seferlik girişler.
YouTube URL'leri Yok Herkese açık YouTube videoları

Not: Çoğu kullanım alanında, özellikle 100 MB'tan büyük dosyalar için veya dosyayı birden fazla istekte yeniden kullanmak istediğinizde File API ö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 videoyu indirir, Files API'yi kullanarak yükler, işlenmesini bekler ve ardından videoyu özetlemek için yüklenen dosya referansını kullanır.

Python

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=[myfile, "Summarize this video. Then create a quiz with an answer key based on the information in this video."]
)

print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/sample.mp4",
    config: { mimeType: "video/mp4" },
  });

  const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: createUserContent([
      createPartFromUri(myfile.uri, myfile.mimeType),
      "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
    ]),
  });
  console.log(response.text);
}

await main();

Go

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

parts := []*genai.Part{
    genai.NewPartFromText("Summarize this video. Then create a quiz with an answer key based on the information in this video."),
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
}

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

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

fmt.Println(result.Text())

REST

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

tmp_header_file=upload-header.tmp

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

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

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

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

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

# --- 3. Generate content using the uploaded video file ---
echo "Generating content from video..."
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data":{"mime_type": "'"${MIME_TYPE}"'", "file_uri": "'"${file_uri}"'"}},
          {"text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}]
        }]
      }' 2> /dev/null > response.json

jq -r ".candidates[].content.parts[].text" response.json

Jeton verimliliğini ve performansını optimize etmek için temsilci tabanlı video işlemeyi kullanabilirsiniz.

Toplam istek boyutu (dosya, metin istemi, sistem talimatları vb. dahil) 20 MB'tan büyükse, video süresi uzunsa 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

Dosya API'sini kullanarak video dosyası yüklemek yerine, daha küçük videoları doğrudan generateContent isteğinde iletebilirsiniz. Bu yöntem, toplam istek boyutu 20 MB'tan küçük olan daha 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
from google.genai import types

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

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(data=video_bytes, mime_type='video/mp4')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const base64VideoFile = fs.readFileSync("path/to/small-sample.mp4", {
  encoding: "base64",
});

const contents = [
  {
    inlineData: {
      mimeType: "video/mp4",
      data: base64VideoFile,
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: contents,
});
console.log(response.text);

REST

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

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

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

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
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=9hE5-98ZeCg')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)
print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

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

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: contents,
});
console.log(response.text);

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

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

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

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

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

  fmt.Println(result.Text())
}

REST

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

Sınırlamalar:

  • Ücretsiz katmanda, günde en fazla 8 saatlik YouTube videosu yükleyebilirsiniz.
  • Ücretli katmanda video uzunluğuna dayalı 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ükleyemezsiniz).

Temsilci tabanlı video yorumlama

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, temsilci video anlama özelliğini de destekler. Bu özellik, modelin video zaman çizelgesini dinamik olarak keşfettiği, transkriptleri seçerek incelediği ve kare hızları ile çözünürlüğü isteme göre anında uyarlayarak 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ı (thoughts_token_count) ve araç çağrısı gidiş dönüşlerini (tool_use_prompt_token_count) önler.
  • Temsilci: Uzun videolar (5-10 dakikadan uzun), samanlıkta iğne arama gibi zorlu aramalar veya belirli anları ya da konuları hedefleyen sorgular için idealdir. Model, önce transkriptleri inceler ve yalnızca alakalı görsel segmentleri isteğe bağlı olarak yükler. Bu sayede, bağlam penceresini doldurmadan video giriş jetonu kullanımı% 88'e kadar azaltılır.

Not: Ajan işleme süresinin daha uzun sürdüğü uzun videolarda veya karmaşık istemlerde akış özelliğini (client.models.generate_content_stream) kullanın. Bu özellik, bağlantıyı etkin tutar, ara akıl yürütme adımlarını gösterir ve bağlantı veya kimlik doğrulama zaman aşımlarını önler.

İşleme modunu ayarlama

Python

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

client = genai.Client()

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

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

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

JavaScript

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

const ai = new GoogleGenAI({});

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

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

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

Go

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

REST

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

Not: Temsilci tabanlı işlemenin kullanıldığını doğrulamak için response.candidates[0].content.parts öğesini inceleyin. MEDIA_PROCESSING araç türüne sahip tool_call ve tool_response bölümlerinin varlığı, modelin videoda dinamik olarak gezindiğini gösterir.

Not: Diğer sunucu tarafı araçların (ör. Google Arama veya URL Bağlamı) aksine, temsilci video için araç çağrılarının ve sonuçların döndürülmesi veya aktarılması amacıyla ToolConfig içinde include_server_side_tool_invocations=True ayarının yapılması gerekmez. media_processing="AGENTIC" herhangi bir giriş parçasında ayarlandığında, video gezinme için tool_call ve tool_response parçaları otomatik olarak döndürülür.

Yanıt yapısı

Temsilci tabanlı işleme etkinleştirildiğinde yanıt, dahili gezinme izini gösteren ek bölümler içerir:

  • tool_call parts (tool_type: "MEDIA_PROCESSING"): Model, video segmenti veya ses transkripti her istediğinde yayınlanır.
  • tool_response parça (tool_type: "MEDIA_PROCESSING"): her yükleme işleminin sonucu.

Bu bölümleri manuel olarak işlemeniz veya yanıtlamanız gerekmez: Tam yanıtı görüşme geçmişi olarak geri iletin. Bu bölümler otomatik olarak işlenir.

include_thoughts=True, ThinkingConfig içinde ayarlanırsa muhakeme adımları, araç çağrısı/yanıt çiftleriyle serpiştirilmiş thought: true bölümleri olarak görünür. Düşünceler devre dışı bırakıldığında düşünce metni atlanır ancak araç parçaları gösterilmeye devam eder.

Aşağıdaki örnekte, aralıklı araç çağrısı ve yanıt bölümleri içeren yanıt yükü gösterilmektedir:

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

Videolarda farklı işleme modlarını kullanma

Aynı istekteki her video bölümü için farklı işleme modları ayarlayabilirsiniz:

Python

from google import genai
from google.genai import types

client = genai.Client()

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

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

JavaScript

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

const ai = new GoogleGenAI({});

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

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

Go

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

REST

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

Uzun videolarda bağlamı önbelleğe alma özelliğini kullanma

10 dakikadan uzun videolar için veya aynı video dosyasına birden fazla istek göndermeyi planladığınızda maliyetleri düşürmek ve gecikmeyi azaltmak için bağlam önbelleğe almayı kullanın. Bağlam önbelleğe alma, videoyu bir kez işleyip jetonları sonraki sorgular için yeniden kullanmanıza olanak tanır. Bu sayede, sohbet oturumları veya uzun içeriklerin tekrar tekrar analiz edilmesi için idealdir.

İçerikteki zaman damgalarına bakın.

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

Python

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        myfile,
        "What are the examples given at 00:05 and 00:10 supposed to show us?",
    ],
)
print(response.text)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    myfile,
    "What are the examples given at 00:05 and 00:10 supposed to show us?",
  ],
});
console.log(response.text);

Go

parts := []*genai.Part{
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
    genai.NewPartFromText("What are the examples given at 00:05 and 00:10 supposed to show us?"),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    []*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data": {"file_uri": "'"${file_uri}"'", "mime_type": "'"${MIME_TYPE}"'"}},
          {"text": "What are the examples given at 00:05 and 00:10 supposed to show us?"}
        ]
      }]
    }' 2> /dev/null

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 videolarda ayrıntıların atlanabileceğini unutmayın. Bu tür yüksek hareketli içerikler için özel bir kare hızı ayarlamayı düşünebilirsiniz.

Python

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        myfile,
        "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.",
    ],
)
print(response.text)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    myfile,
    "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.",
  ],
});
console.log(response.text);

Go

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

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    []*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data": {"file_uri": "'"${file_uri}"'", "mime_type": "'"${MIME_TYPE}"'"}},
          {"text": "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."}
        ]
      }]
    }' 2> /dev/null

Video işlemeyi özelleştirme

Kırpma aralıkları ayarlayarak veya özel kare hızı örnekleme 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

Başlangıç ve bitiş ofsetleriyle videoMetadata belirterek videoyu kırpabilirsiniz.

Python

from google import genai
from google.genai import types

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

JavaScript

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

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

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

console.log(response.text)

}

await main();

Özel kare hızı ayarlama

fps işlevine videoMetadata bağımsız değişkenini ileterek özel kare hızı örneklemesi ayarlayabilirsiniz.

Python

from google import genai
from google.genai import types

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

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-3.8-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=video_bytes,
                    mime_type='video/mp4'),
                video_metadata=types.VideoMetadata(fps=5)
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

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

const ai = new GoogleGenAI({});

const myfile = await ai.files.upload({
  file: "path/to/sample.mp4",
  mimeType: "video/mp4",
});

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      fileData: {
        fileUri: myfile.uri,
        mimeType: myfile.mimeType,
      },
      videoMetadata: {
        fps: 5,
      },
    },
    "Please summarize the video in 3 sentences.",
  ],
});

console.log(response.text);

Varsayılan olarak videodan saniyede 1 kare (FPS) örneklenir. Uzun videolarda düşük FPS (< 1) ayarlayabilirsiniz. Bu, özellikle çoğunlukla statik olan videolar (ör. dersler) için kullanışlıdır. Hızlı hareketleri anlama veya yüksek hızlı hareket izleme gibi ayrıntılı zamansal analiz gerektiren videolar için daha yüksek bir FPS kullanın.

Desteklenen video biçimleri

Gemini, aşağıdaki video formatı MIME türlerini destekler:

  • video/mp4
  • video/mpeg
  • video/quicktime
  • 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 en iyisidir. 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. Yanıtlar, sıralar arasında akıl yürütme bağlamını korumak için MEDIA_PROCESSING araç çağrısı ve yanıt bölümleri içerir. Uzun videolar ve hedefli sorgular için en iyisidir. Bu model, jeton maliyetlerini ve yanıt kalitesini optimize eder. 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 gibi 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üşünme jetonları (thoughts_token_count) olarak kabul edilirken isteğe bağlı olarak yüklenen kareler, ses ve transkriptler araç istemi jetonları (tool_use_prompt_token_count) olarak kabul edilir. Agentic işleme, uzun içeriklerde genellikle statik işlemeye kıyasla% 88'e kadar daha az toplam jeton kullanır. Bunun nedeni, modelin isteme yanıt vermek için yalnızca transkripti ve/veya kareleri ve/veya sesi yüklemesidir (jeton kılavuzuna bakın).
  • Medya çözünürlüğü: Gemini 3, media_resolution parametresiyle çok formatlı görüntü işleme üzerinde ayrıntılı kontrol imkanı sunar. 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 media_processing parametreleri birbirinden bağımsızdır. Aynı video bölümünde her ikisini de 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 video birleştiriliyorsa metin istemini contents dizisinde video bölümünden sonra yerleştirin.
  • Uzun istekler için zaman aşımı: Uzun işleme süresi veya karmaşık çok adımlı akıl yürütme gerektiren videolar için akış (client.models.generate_content_stream) kullanın. Yoğun talep altında arka uç yeniden denemeleri yaşayan eşzamanlı, akış dışı istekler, bağlantı veya kimlik doğrulama jetonu geçerlilik pencerelerini aşabilir. Bu durum, beklenmedik 401 Unauthorized veya zaman aşımı hataları olarak ortaya çıkabilir. Akış, bağlantıyı etkin tutar ve ara akıl yürütme 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.
  • Jetonlar: Video içeriğinin hem statik hem de temsilci tabanlı işleme modlarında nasıl jetonlara dönüştürüldüğünü öğrenin.
  • Sistem talimatları: Sistem talimatları, modelin davranışını özel ihtiyaçlarınıza ve kullanım alanlarınıza göre yönlendirmenize olanak tanır.
  • 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.