Video anlama

Gemini modelleri, videoları işleyebilir. Bu sayede, geçmişte alana özel modeller gerektiren birçok yeni geliştirici kullanım alanı mümkün olur. Gemini'ın görme özelliklerinden bazıları:

  • Videoları açıklama, segmentlere ayırma ve videolardan bilgi çıkarma
  • Video içeriğiyle ilgili soruları yanıtlama
  • Videodaki belirli zaman damgalarına referans verme

Gemini, baştan sona çok formatlı olacak şekilde tasarlandı ve yapabileceklerimizin sınırlarını zorlamaya devam ediyoruz. Bu kılavuzda, video girişlerine dayalı metin yanıtları oluşturmak için Gemini API'nin nasıl kullanılacağı gösterilmektedir.

Video girişi

Gemini'a aşağıdaki yöntemlerle video girişi sağlayabilirsiniz:

  • generateContent'ye istekte bulunmadan önce File API'yi kullanarak video dosyası yükleyin. 20 MB'tan büyük dosyalar, yaklaşık 1 dakikadan uzun videolar veya dosyayı birden fazla istekte yeniden kullanmak istediğinizde bu yöntemi kullanın.
  • İsteğiyle generateContent satır içi video verilerini iletin. Bu yöntemi daha küçük dosyalar (<20 MB) ve daha kısa süreler için kullanın.
  • İsteme doğrudan YouTube URL'si ekleyin.

Video dosyası yükleme

Video dosyası yüklemek için Files API'yi 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 kullanmayı planlıyorsanız her zaman Files API'yi kullanın. File API, video dosyası biçimlerini doğrudan kabul eder.

Aşağıdaki kod, örnek videoyu indirir, File API'yi kullanarak yükler, işlenmesini bekler ve ardından generateContent isteğinde 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-2.5-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-2.5-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-2.5-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-2.5-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

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

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ğine iletebilirsiniz. Bu, toplam istek boyutu 20 MB'tan az olan kısa videolar için uygundur.

Satır içi video verileri sağlama örneğini burada bulabilirsiniz:

Python

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

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

JavaScript

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

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

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

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

REST

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

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

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

Gemini API ve AI Studio, YouTube URL'lerini dosya verisi olarak destekler Part. Modele videoyu özetlemesini, çevirmesini veya video içeriğiyle başka bir şekilde etkileşime geçmesini isteyen bir istemle birlikte YouTube URL'si ekleyebilirsiniz.

Sınırlamalar:

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

Aşağıdaki örnekte, istemle birlikte YouTube URL'sinin nasıl ekleneceği gösterilmektedir:

Python

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

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro" });
const result = await model.generateContent([
  "Please summarize the video in 3 sentences.",
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
]);
console.log(result.response.text());

Go

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-2.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

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

İç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?" # Adjusted timestamps for the NASA video

JavaScript

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

Go

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
         // Adjusted timestamps for the NASA video
        genai.NewPartFromText("What are the examples given at 00:05 and " +
            "00:10 supposed to show us?"),
    }

REST

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

Videoyu metne dönüştürme ve görsel açıklamalar sağlama

Gemini modelleri, hem ses parçasını hem de görsel kareleri işleyerek video içeriklerinin transkriptini oluşturabilir ve görsel açıklamalarını sağlayabilir. Görsel açıklamalar için model, videoyu saniyede 1 kare hızında örnekler. Bu örnekleme hızı, özellikle görselleri hızla değişen videolarda açıklamaların ayrıntı düzeyini etkileyebilir.

Python

prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

JavaScript

const prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions.";

Go

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
        genai.NewPartFromText("Transcribe the audio from this video, giving timestamps for salient events in the video. Also " +
            "provide visual descriptions."),
    }

REST

PROMPT="Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

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.

Kırpma aralıklarını ayarlama

Başlangıç ve bitiş zamanlarını belirterek videoMetadata ile video klip oluşturabilirsiniz.

Python

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

Özel bir kare hızı ayarlama

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

Python

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

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

Varsayılan olarak videodan saniyede 1 kare (FPS) örneklenir. Uzun videolar için düşük FPS (< 1) ayarlamak isteyebilirsiniz. Bu özellik, özellikle çoğunlukla statik olan videolar (ör. dersler) için yararlıdır. Hızlı değişen görsellerde daha fazla ayrıntı yakalamak istiyorsanız daha yüksek bir FPS değeri ayarlayabilirsiniz.

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 2.0 ve 2.5 modelleri video verilerini işleyebilir.
    • 2 milyon parçalık bağlam penceresine sahip modeller, varsayılan medya çözünürlüğünde 2 saate kadar, düşük medya çözünürlüğünde ise 6 saate kadar uzunluktaki videoları işleyebilir. 1 milyon parçalık bağlam penceresine sahip modeller ise varsayılan medya çözünürlüğünde 1 saate kadar, düşük medya çözünürlüğünde ise 3 saate kadar uzunluktaki videoları işleyebilir.
  • File API işleme: File API kullanılırken videolar saniyede 1 kare (FPS) hızında örneklenir ve ses 1 Kbps (tek kanal) hızında işlenir. Zaman damgaları her saniye eklenir.
    • Bu oranlar, çıkarım iyileştirmeleri için gelecekte değişebilir.
  • Jeton hesaplama: Videonun her saniyesi aşağıdaki gibi jetonlaştırılır:
    • Tek tek kareler (1 FPS'de örneklenir):
      • mediaResolution 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 jetonlaştırılır.
    • Ses: Saniyede 32 jeton.
    • Meta veriler de dahildir.
    • Toplam: Varsayılan medya çözünürlüğünde video saniyesi başına yaklaşık 300 jeton veya düşük medya çözünürlüğünde video saniyesi başına 100 jeton.
  • Zaman damgası biçimi: İsteminizde bir videodaki belirli anlardan bahsederken MM:SS biçimini kullanın (ör. 01:15 için 1 dakika 15 saniye).
  • En iyi uygulamalar:
    • En iyi sonuçları elde etmek için istem isteği başına yalnızca bir video kullanın.
    • Metin ve tek bir videoyu birleştiriyorsanız metin istemini contents dizisindeki video bölümünün sonrasına yerleştirin.
    • Hızlı hareket dizilerinin, 1 FPS örnekleme hızı nedeniyle ayrıntı kaybedebileceğini unutmayın. Gerekirse bu tür klipleri yavaşlatabilirsiniz.

Sırada ne var?

Bu kılavuzda, video dosyalarının nasıl yükleneceği ve video girişlerinden nasıl metin çıkışları oluşturulacağı gösterilmektedir. Daha fazla bilgi edinmek için aşağıdaki kaynaklara göz atı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 istemi destekler.
  • Güvenlik yönergeleri: Üretken yapay zeka modelleri bazen yanlış, taraflı veya rahatsız edici gibi beklenmedik çıkışlar üretebilir. Bu tür çıkışlardan kaynaklanan zarar riskini sınırlamak için son işlem ve uzman değerlendirmesi şarttır.