Video anlama

Gemini modelleri videoları işleyebilir. Böylece, geçmişte alana özgü modeller gerektiren birçok yenilikçi geliştirici kullanım alanı mümkün olur. Gemini'nin görüntüleme özelliklerinden bazıları şunlardır:

  • 90 dakikaya kadar uzunluktaki videoları tanımlama, segmentlere ayırma ve videolardan bilgi ayıklama
  • Video içeriğiyle ilgili soruları yanıtlama
  • Videodaki belirli zaman damgalarına referans verme

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

Başlamadan önce

Gemini API'yi çağırmadan önce seçtiğiniz SDK'nın yüklü olduğundan ve Gemini API anahtarının yapılandırılmış ve kullanıma hazır olduğundan emin olun.

Video girişi

Gemini'ye video girişi aşağıdaki şekillerde sağlanabilir:

  • generateContent'ye istek göndermeden önce File API'yi kullanarak bir 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.
  • generateContent isteğiyle 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 bir 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ük olduğunda, video süresi önemli olduğunda veya aynı videoyu birden fazla istemde kullanmayı planlıyorsanız her zaman Files API'yi kullanın.

File API, video dosya biçimlerini doğrudan kabul eder. Bu örnekte, NASA'nın "Jüpiter'in Büyük Kırmızı Lekesi Küçülüyor ve Büyüyor" adlı kısa filmi kullanılmıştır. Fotoğraf: Goddard Uzay Uçuş Merkezi (GSFC)/David Ladd (2018).

"Jupiter's Great Red Spot Shrinks and Grows" (Jüpiter'in Büyük Kırmızı Lekesi Küçülüp Büyüyor) herkese açık bir alanda bulunuyor ve kimliği tanımlanabilir kişiler göstermiyor. (NASA resim ve medya kullanım kuralları.)

Aşağıdaki kod, örnek videoyu indirir, File API'yi kullanarak yükler, işlenmesini bekler ve ardından dosya referansını bir generateContent isteğinde kullanır.

Python

from google import genai

client = genai.Client(api_key="GOOGLE_API_KEY")

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

response = client.models.generate_content(
    model="gemini-2.0-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({ apiKey: "GOOGLE_API_KEY" });

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.0-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

file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp4", nil)
if err != nil {
    log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
    genai.FileData{URI: file.URI},
    genai.Text("Summarize this video. Then create a quiz with an answer key based on the information in this video."))
if err != nil {
    log.Fatal(err)
}

printResponse(resp)

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?key=${GOOGLE_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.0-flash:generateContent?key=$GOOGLE_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 başlıklı makaleyi inceleyin.

Video verilerini satır içi olarak iletme

File API'yi kullanarak video dosyası yüklemek yerine, daha küçük videoları doğrudan generateContent isteğine iletebilirsiniz. Bu, toplam istek boyutu 20 MB'ın altında olan kısa videolar için uygundur.

Satır içi video verileri sağlama örneğini aşağıda 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.0-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({ apiKey: "GOOGLE_API_KEY" });
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.0-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.0-flash:generateContent?key=$GOOGLE_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 Part olarak destekler. Modelden video içeriğini özetlemesini, çevirmesini veya başka bir şekilde etkileşim kurmasını isteyen bir istem içeren bir YouTube URL'si ekleyebilirsiniz.

Sınırlamalar:

  • Günde 8 saatten fazla YouTube videosu yükleyemezsiniz.
  • Her istek için yalnızca 1 video yükleyebilirsiniz.
  • Yalnızca herkese açık videolar yükleyebilirsiniz (gizli veya liste dışı videolar yükleyemezsiniz).

Aşağıdaki örnekte, istem içeren bir YouTube URL'sinin nasıl ekleneceği gösterilmektedir:

Python

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

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GOOGLE_API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
  genai.FileData{URI: "https://www.youtube.com/watch?v=9hE5-98ZeCg"},
  genai.Text("Please summarize the video in 3 sentences."))
if err != nil {
  log.Fatal(err)
}

// Handle the response of generated text.
for _, c := range resp.Candidates {
  if c.Content != nil {
    fmt.Println(*c.Content)
  }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_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 atıfta bulunma

MM:SS biçimindeki zaman damgalarını kullanarak videodaki belirli noktalarla ilgili 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.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
         // Adjusted timestamps for the NASA video
        genai.Text("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çeriğini metne dönüştürebilir ve görsel açıklamaları sunabilir. Görsel açıklamalar için model, videoyu saniyede 1 kare hızında örnekler. Bu örnekleme hızı, özellikle hızlıca değişen görsellerin yer aldığı 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.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
        genai.Text("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."

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 bağlam aralığına sahip modeller 2 saate kadar videoları, 1 milyon bağlam aralığına sahip modeller ise 1 saate kadar videoları işleyebilir.
  • File API işleme: File API kullanılırken videolar saniyede 1 kare (FPS) hızında örneklenir ve ses 1 Kb/sn (tek kanal) hızında işlenir. Zaman damgaları her saniye eklenir.
    • Bu oranlar, gelecekte çıkarımlarda iyileştirmeler yapılması için değiştirilebilir.
  • Jeton hesaplama: Videonun her saniyesinde aşağıdaki şekilde jeton oluşturulur:
    • Tek kareler (1 FPS'de örneklenir): Kare başına 258 jeton.
    • Ses: Saniyede 32 jeton.
    • Meta veriler de dahildir.
    • Toplam: Videonun her saniyesinde yaklaşık 300 jeton.
  • Zaman damgası biçimi: İsteminizde videodaki belirli anlara atıfta bulunurken MM:SS biçimini kullanın (ör. 01:15 1 dakika 15 saniye).
  • En iyi uygulamalar:
    • En iyi sonuçlar 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 ardından yerleştirin.
    • Hızlı aksiyon sekanslarının 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 metin çıkışlarının nasıl oluşturulacağı gösterilmektedir. Daha fazla bilgi edinmek için aşağıdaki kaynakları inceleyin:

  • Sistem talimatları: Sistem talimatları, modelin davranışını belirli ihtiyaçlarınıza ve kullanım alanlarınıza göre yönlendirmenize olanak tanır.
  • Files API: Gemini ile kullanmak üzere dosya yükleme ve yönetme hakkında daha fazla bilgi edinin.
  • Dosya istemi stratejileri: Gemini API, çoklu formatlı istem olarak da bilinen metin, resim, ses ve video verileriyle istemleri destekler.
  • Güvenlik kılavuzu: Üretken yapay zeka modelleri bazen yanlış, önyargılı veya rahatsız edici sonuçlar gibi beklenmedik sonuçlar üretebilir. Bu tür çıkışlardan kaynaklanan zarar riskini sınırlamak için işlem sonrası ve gerçek kişiler tarafından değerlendirme yapılması önemlidir.