การทำความเข้าใจวิดีโอ

ดูข้อมูลเกี่ยวกับการสร้างวิดีโอได้ในคำแนะนำสำหรับ Gemini Omni Flash

โมเดล Gemini สามารถประมวลผลวิดีโอได้ ซึ่งช่วยให้ผู้พัฒนาที่อยู่แถวหน้าสามารถใช้กรณีการใช้งานต่างๆ ที่ในอดีตต้องใช้โมเดลเฉพาะโดเมน ความสามารถด้านการมองเห็นของ Gemini บางอย่าง ได้แก่ ความสามารถในการอธิบาย แบ่งกลุ่ม และดึงข้อมูลจากวิดีโอ ตอบคำถามเกี่ยวกับเนื้อหาวิดีโอ และ อ้างอิงการประทับเวลาที่เฉพาะเจาะจงภายในวิดีโอ

คุณสามารถป้อนวิดีโอให้กับ Gemini ได้ด้วยวิธีต่อไปนี้

วิธีการป้อนข้อมูล ขนาดสูงสุด กรณีการใช้งานที่แนะนำ
File API 20 GB (แบบชำระเงิน) / 2 GB (ฟรี) ไฟล์ขนาดใหญ่ (100 MB ขึ้นไป), วิดีโอยาว (10 นาทีขึ้นไป), ไฟล์ที่นำกลับมาใช้ซ้ำได้
การลงทะเบียน Cloud Storage 2 GB (ต่อไฟล์ ไม่มีขีดจำกัดพื้นที่เก็บข้อมูล) ไฟล์ขนาดใหญ่ (100 MB ขึ้นไป), วิดีโอยาว (10 นาทีขึ้นไป), ไฟล์ที่ใช้ซ้ำได้
ข้อมูลในบรรทัด < 100MB ไฟล์ขนาดเล็ก (น้อยกว่า 100 MB), ระยะเวลาสั้น (น้อยกว่า 1 นาที), อินพุตแบบครั้งเดียว
URL ของ YouTube ไม่มี วิดีโอ YouTube สาธารณะ

หมายเหตุ: เราขอแนะนำให้ใช้ File API สำหรับ Use Case ส่วนใหญ่ โดยเฉพาะอย่างยิ่งสำหรับไฟล์ที่มีขนาดใหญ่กว่า 100 MB หรือเมื่อคุณต้องการนำไฟล์ไปใช้ซ้ำในคำขอหลายรายการ

ดูข้อมูลเกี่ยวกับวิธีการป้อนไฟล์อื่นๆ เช่น การใช้ URL ภายนอกหรือไฟล์ที่จัดเก็บไว้ใน Google Cloud ได้ที่คู่มือวิธีการป้อนไฟล์

อัปโหลดไฟล์วิดีโอ

โค้ดต่อไปนี้จะดาวน์โหลดวิดีโอตัวอย่าง อัปโหลดโดยใช้ Files API รอให้ประมวลผล แล้วใช้การอ้างอิงไฟล์ที่อัปโหลดเพื่อ สรุปวิดีโอ

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

โปรดพิจารณาใช้การประมวลผลวิดีโอแบบเอเจนต์เพื่อเพิ่มประสิทธิภาพและประสิทธิภาพของโทเค็น

ใช้ Files API เสมอเมื่อขนาดคำขอทั้งหมด (รวมถึงไฟล์ พรอมต์ข้อความ คำสั่งของระบบ ฯลฯ) ใหญ่กว่า 20 MB, ความยาววิดีโอมีความสำคัญ หรือหากคุณต้องการใช้วิดีโอเดียวกันในพรอมต์หลายรายการ File API ยอมรับรูปแบบไฟล์วิดีโอโดยตรง

ดูข้อมูลเพิ่มเติมเกี่ยวกับการทำงานกับไฟล์สื่อได้ที่ Files API

ส่งข้อมูลวิดีโอแบบอินไลน์

คุณสามารถส่งวิดีโอขนาดเล็กกว่า ในคำขอไปยัง generateContent ได้โดยตรงแทนที่จะอัปโหลดไฟล์วิดีโอโดยใช้ File API วิธีนี้เหมาะสำหรับ วิดีโอสั้นๆ ที่มีขนาดคำขอรวมไม่เกิน 20 MB

ตัวอย่างการระบุข้อมูลวิดีโอในบรรทัดมีดังนี้

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

ส่ง URL ของ YouTube

คุณส่ง URL ของ YouTube ไปยัง Gemini API ได้โดยตรงเป็นส่วนหนึ่งของคำขอ ดังนี้

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

ข้อจำกัด:

  • สำหรับแพ็กเกจฟรี คุณจะอัปโหลดวิดีโอ YouTube ได้ไม่เกิน 8 ชั่วโมงต่อวัน
  • สำหรับแพ็กเกจแบบชำระเงิน จะไม่มีการจำกัดตามความยาวของวิดีโอ
  • สำหรับโมเดลก่อน Gemini 2.5 คุณจะอัปโหลดวิดีโอได้เพียง 1 รายการต่อคำขอ สำหรับโมเดล Gemini 2.5 ขึ้นไป คุณจะอัปโหลดวิดีโอได้สูงสุด 10 รายการต่อคำขอ
  • คุณอัปโหลดได้เฉพาะวิดีโอสาธารณะ (ไม่ใช่ส่วนตัวหรือที่ไม่เป็นสาธารณะ)

การทำความเข้าใจวิดีโอแบบ Agent

โดยค่าเริ่มต้น อินพุตวิดีโอจะใช้การประมวลผลแบบคงที่ (ดึงเฟรมที่ 1 FPS) โมเดล Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash และ 3.5 Flash Lite ยังรองรับการทำความเข้าใจวิดีโอแบบเอเจนต์ ซึ่งโมเดลจะสำรวจไทม์ไลน์วิดีโอแบบไดนามิก ตรวจสอบข้อความถอดเสียงอย่างเลือกสรร และปรับอัตราเฟรมและความละเอียดแบบปรับเปลี่ยนได้ทันทีตามพรอมต์

โหมด คำอธิบาย รุ่นที่รองรับ
คงที่ (ค่าเริ่มต้น) แยกเฟรมในอัตราคงที่ (1 FPS) และวางเฟรมเหล่านั้นลงในบริบทในการส่งผ่านครั้งเดียว เหมาะสำหรับคลิปสั้นๆ โมเดล Gemini ทั้งหมด
การทำงานแบบเป็น Agent โมเดลจะไปยังไทม์ไลน์ของวิดีโอแบบไดนามิก โดยจะโหลดเฉพาะเนื้อหาที่ต้องการตามพรอมต์ ประหยัดโทเค็นมากขึ้นสูงสุด 88% และมีคุณภาพสูงขึ้นประมาณ 7% ในเนื้อหารูปแบบยาว Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite

เลือกโหมดการประมวลผล

โดยหลักเกณฑ์ทั่วไป ให้เริ่มต้นด้วยโหมดเอเจนต์ โดยเฉพาะเมื่อเพิ่มประสิทธิภาพ เพื่อคุณภาพการตอบกลับหรือประสิทธิภาพของโทเค็น

  • Agentic: วิดีโอแบบยาวหรือคำค้นหาที่กำหนดเป้าหมายไปยังช่วงเวลาที่เฉพาะเจาะจง โมเดลจะไปยังไทม์ไลน์แบบไดนามิกเพื่อกำหนดเป้าหมายข้อมูลที่เกี่ยวข้องตามบริบท โดยไม่ต้องกรอกหน้าต่างบริบท
  • คงที่: คำค้นหาที่คำนึงถึงเวลาในการตอบสนองในคลิปสั้น (ไม่เกิน 5 นาที) หรือ กรณีที่ต้องการความแม่นยำระดับเฟรมตลอดทั้งคลิป

หมายเหตุ: สำหรับวิดีโอขนาดยาวหรือพรอมต์ที่ซับซ้อนซึ่งการประมวลผลแบบเอเจนต์ใช้เวลานานกว่า ให้ใช้การสตรีม (client.models.generate_content_stream) วิธีนี้จะช่วยให้การเชื่อมต่อยังคงใช้งานได้ แสดงขั้นตอนการให้เหตุผลระดับกลาง และหลีกเลี่ยงการหมดเวลาการเชื่อมต่อหรือการตรวจสอบสิทธิ์

ตั้งค่าโหมดการประมวลผล

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?"}
      ]
    }]
  }'

หมายเหตุ: หากต้องการยืนยันว่ามีการใช้การประมวลผลแบบเอเจนต์ ให้ตรวจสอบ response.candidates[0].content.parts การมีอยู่ของส่วน tool_call และ tool_response ที่มีประเภทเครื่องมือ MEDIA_PROCESSING แสดงว่าโมเดลไปยังส่วนต่างๆ ของวิดีโอแบบไดนามิก

หมายเหตุ: วิดีโอที่ทำงานโดยเอเจนต์ไม่จำเป็นต้องตั้งค่า include_server_side_tool_invocations=True ใน ToolConfig เพื่อให้ระบบแสดงหรือสตรีมการเรียกใช้เครื่องมือและผลลัพธ์ ซึ่งแตกต่างจากเครื่องมือฝั่งเซิร์ฟเวอร์อื่นๆ (เช่น Google Search หรือบริบท URL ) ระบบจะแสดงส่วน tool_call และ tool_response สำหรับการไปยังส่วนต่างๆ ของวิดีโอโดยอัตโนมัติเมื่อตั้งค่า media_processing="AGENTIC" ในส่วนอินพุตใดก็ตาม

โครงสร้างการตอบกลับ

เมื่อเปิดใช้การประมวลผลแบบเอเจนต์ คำตอบจะมีส่วนเพิ่มเติมที่แสดงร่องรอยการนำทางภายใน ดังนี้

  • tool_call ชิ้นส่วน (tool_type: "MEDIA_PROCESSING"): ปล่อยออกมาทุกครั้งที่โมเดลขอส่วนวิดีโอหรือข้อความถอดเสียง
  • tool_response ชิ้นส่วน (tool_type: "MEDIA_PROCESSING"): ผลลัพธ์ของการดำเนินการโหลดแต่ละครั้ง

คุณไม่จำเป็นต้องจัดการหรือตอบกลับส่วนเหล่านี้ด้วยตนเอง เพียงส่งการตอบกลับทั้งหมดกลับเป็นประวัติการสนทนา แล้วระบบจะจัดการโดยอัตโนมัติ

หากตั้งค่า include_thoughts=True ใน ThinkingConfig ขั้นตอนการให้เหตุผลจะปรากฏเป็นส่วน thought: true ที่สลับกับคู่การเรียกใช้/การตอบกลับเครื่องมือ เมื่อปิดใช้ความคิด ระบบจะละเว้นข้อความความคิด แต่ชิ้นส่วนเครื่องมือจะยังคงอยู่

ตัวอย่างต่อไปนี้แสดงเพย์โหลดการตอบกลับที่มีการเรียกใช้เครื่องมือและการตอบกลับแบบสลับ

{
  "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"
          }
        ]
      }
    }
  ]
}

ใช้โหมดการประมวลผลที่หลากหลายในวิดีโอ

คุณตั้งค่าโหมดการประมวลผลที่แตกต่างกันสำหรับแต่ละส่วนของวิดีโอในคำขอเดียวกันได้โดยทำดังนี้

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."}
      ]
    }]
  }'

ใช้การแคชบริบทสำหรับวิดีโอแบบยาว

สำหรับวิดีโอที่ยาวกว่า 10 นาที หรือเมื่อคุณวางแผนที่จะส่งคำขอหลายรายการ กับไฟล์วิดีโอเดียวกัน ให้ใช้การแคชบริบทเพื่อ ลดต้นทุนและปรับปรุงเวลาในการตอบสนอง การแคชบริบทช่วยให้คุณประมวลผลวิดีโอ ได้ครั้งเดียวและนำโทเค็นกลับมาใช้ใหม่สำหรับการค้นหาครั้งต่อๆ ไป ซึ่งเหมาะอย่างยิ่งสำหรับเซสชันแชท หรือการวิเคราะห์เนื้อหาแบบยาวซ้ำๆ

อ้างอิงการประทับเวลาในเนื้อหา

คุณสามารถถามคำถามเกี่ยวกับช่วงเวลาที่เฉพาะเจาะจงภายในวิดีโอได้โดยใช้ การประทับเวลาในรูปแบบ MM:SS

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

ดึงข้อมูลเชิงลึกโดยละเอียดจากวิดีโอ

โมเดล Gemini มีความสามารถอันทรงพลังในการทำความเข้าใจเนื้อหาวิดีโอโดย การประมวลผลข้อมูลจากทั้งสตรีมเสียงและภาพ ซึ่งช่วยให้คุณ ดึงรายละเอียดที่หลากหลายได้ รวมถึงสร้างคำอธิบายสิ่งที่ เกิดขึ้นในวิดีโอและตอบคำถามเกี่ยวกับเนื้อหาของวิดีโอ

สำหรับคำอธิบายภาพ โมเดลจะสุ่มตัวอย่างวิดีโอที่อัตรา 1 เฟรม ต่อวินาที (FPS) อัตราการสุ่มตัวอย่างเริ่มต้นนี้เหมาะกับเนื้อหาส่วนใหญ่ แต่โปรดทราบว่าอาจพลาดรายละเอียดในวิดีโอที่มีการเคลื่อนไหวอย่างรวดเร็วหรือการเปลี่ยนฉากอย่างรวดเร็ว สำหรับเนื้อหาที่มีการเคลื่อนไหวสูงเช่นนี้ ให้ลองตั้งค่าอัตราเฟรมที่กำหนดเอง

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

ปรับแต่งการประมวลผลวิดีโอ

คุณปรับแต่งการประมวลผลวิดีโอใน Gemini API ได้โดยการตั้งค่าช่วงการตัด หรือระบุการสุ่มตัวอย่างอัตราเฟรมที่กำหนดเอง ตัวเลือกการปรับแต่งเหล่านี้ จะใช้ได้เมื่อประมวลผลวิดีโอในโหมด "static" เท่านั้น

ตั้งค่าช่วงการตัด

คุณตัดคลิปวิดีโอได้โดยระบุ videoMetadata พร้อมออฟเซ็ตเริ่มต้นและสิ้นสุด

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();

ตั้งค่าอัตราเฟรมที่กำหนดเอง

คุณตั้งค่าการสุ่มตัวอย่างอัตราเฟรมที่กำหนดเองได้โดยส่งอาร์กิวเมนต์ fps ไปยัง videoMetadata

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);

โดยค่าเริ่มต้น ระบบจะสุ่มตัวอย่าง 1 เฟรมต่อวินาที (FPS) จากวิดีโอ คุณอาจต้องการ ตั้งค่า FPS ต่ำ (< 1) สำหรับวิดีโอยาว ซึ่งมีประโยชน์อย่างยิ่งสำหรับวิดีโอที่ส่วนใหญ่เป็นภาพนิ่ง (เช่น การบรรยาย) ใช้ FPS ที่สูงขึ้นสำหรับวิดีโอที่ต้องมีการวิเคราะห์ชั่วคราวแบบละเอียด เช่น การทำความเข้าใจฉากที่เคลื่อนไหวอย่างรวดเร็วหรือการติดตามการเคลื่อนไหวความเร็วสูง

รูปแบบวิดีโอที่รองรับ

Gemini รองรับประเภท MIME ของรูปแบบวิดีโอต่อไปนี้

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

รายละเอียดทางเทคนิคเกี่ยวกับวิดีโอ

  • โมเดลและบริบทที่รองรับ: โมเดล Gemini ทุกรุ่นสามารถประมวลผลข้อมูลวิดีโอได้
    • โมเดลที่มีหน้าต่างบริบทขนาด 1 ล้านสามารถประมวลผลวิดีโอที่มีความยาวสูงสุด 3 ชั่วโมงโดยค่าเริ่มต้น (ที่ความละเอียดของสื่อต่ำ) หรือยาวสูงสุด 1 ชั่วโมงที่ความละเอียดของสื่อสูง
  • โหมดการประมวลผล: Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite และโมเดลที่ใหม่กว่ารองรับโหมดการประมวลผลวิดีโอ 2 โหมด
    • คงที่: ระบบจะดึงข้อมูลเฟรมที่ 1 FPS และวางลงในบริบท (ค่าเริ่มต้น สำหรับโมเดลทั้งหมด) ระบบจะประมวลผลเสียงที่ 1Kbps (ช่องเดียว) ระบบจะเพิ่มการประทับเวลาทุกวินาที เหมาะที่สุดสำหรับคลิปสั้นๆ หรือเมื่อทุกเฟรม มีความสำคัญ (เช่น การตรวจสอบทีละเฟรม) โปรดทราบว่าฉากที่มีการเคลื่อนไหวรวดเร็ว อาจสูญเสียรายละเอียดเนื่องจากอัตราการสุ่มตัวอย่าง 1 FPS
    • Agentic: โมเดลจะไปยังส่วนต่างๆ ของวิดีโอแบบไดนามิก โดยจะโหลด ข้อความถอดเสียงและ/หรือเฟรมและ/หรือเสียงตามคำขอ ซึ่งจะใช้โทเค็นน้อยลงสูงสุด 88% สำหรับเนื้อหาแบบยาว แม้ว่าการนำทางอาจ เพิ่มเวลาในการรับโทเค็นแรก (TTFT) เล็กน้อยในคลิปสั้นๆ (น้อยกว่า 5 นาที) เนื่องจาก การให้เหตุผลภายในและการเดินทางไปกลับของเครื่องมือก่อนที่จะเริ่มสร้าง คำตอบประกอบด้วยMEDIA_PROCESSINGการเรียกใช้เครื่องมือและส่วนการตอบกลับเพื่อ รักษาบริบทการให้เหตุผลในแต่ละรอบ เหมาะที่สุดสำหรับวิดีโอแบบยาวเพื่อ เพิ่มประสิทธิภาพต้นทุนโทเค็นและคุณภาพคำตอบ รองรับใน Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash และ 3.5 Flash Lite ดูรายละเอียดได้ที่การทำความเข้าใจวิดีโอแบบเอเจนต์
  • การคำนวณโทเค็น (โหมดคงที่): ระบบจะแปลงวิดีโอแต่ละวินาทีเป็นโทเค็นดังนี้
    • เฟรมแต่ละเฟรม (สุ่มตัวอย่างที่ 1 FPS)
      • หากตั้งค่า media_resolution เป็นต่ำ ระบบจะแปลงเฟรมเป็นโทเค็นที่ 66 โทเค็นต่อเฟรม
      • ไม่เช่นนั้น ระบบจะแปลงเฟรมเป็นโทเค็นที่ 258 โทเค็นต่อเฟรม
    • เสียง: 32 โทเค็นต่อวินาที
    • รวมถึงข้อมูลเมตาด้วย
    • ทั้งหมด: ประมาณ 100 โทเค็นต่อวินาทีของวิดีโอที่ความละเอียดสื่อเริ่มต้น (ต่ำ) หรือประมาณ 300 โทเค็นต่อวินาทีของวิดีโอที่ความละเอียดสื่อสูง
  • การคำนวณโทเค็น (โหมดเอเจนต์): การใช้โทเค็นจะแตกต่างกันไปตามความซับซ้อนของเนื้อหาและกลยุทธ์การนำทางของโมเดล โทเค็นการให้เหตุผลในการนำทาง ที่สร้างขึ้นระหว่างการสำรวจวิดีโอจะถือเป็นโทเค็นการคิด (thoughts_token_count) ส่วนเฟรม เสียง และข้อความถอดเสียงที่โหลดตามคำขอจะถือเป็นโทเค็นพรอมต์เครื่องมือ (tool_use_prompt_token_count) โดยปกติแล้วการประมวลผลแบบเอเจนต์จะใช้โทเค็นรวมน้อยกว่าการประมวลผลแบบคงที่ถึง 88% สำหรับเนื้อหารูปแบบยาว เนื่องจากโมเดลจะโหลดเฉพาะข้อความถอดเสียงและ/หรือเฟรมและ/หรือเสียงที่จำเป็นต่อการตอบพรอมต์ (ดูคำแนะนำเกี่ยวกับโทเค็น)
  • ความละเอียดของสื่อ: Gemini 3 มีการควบคุมการประมวลผลภาพหลายรูปแบบอย่างละเอียดด้วยพารามิเตอร์ media_resolution พารามิเตอร์ media_resolution จะกำหนดจำนวนโทเค็นสูงสุด ที่จัดสรรต่อรูปภาพอินพุตหรือเฟรมวิดีโอ ความละเอียดที่สูงขึ้นจะช่วยปรับปรุงความสามารถของโมเดลในการอ่านข้อความขนาดเล็กหรือระบุรายละเอียดเล็กๆ แต่จะเพิ่มการใช้โทเค็นและเวลาในการตอบสนอง พารามิเตอร์ media_resolution และ media_processing เป็นอิสระต่อกัน คุณตั้งค่าทั้ง 2 พารามิเตอร์ในวิดีโอพาร์ทเดียวกันได้

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการคำนวณโทเค็นได้ที่คู่มือโทเค็น

  • รูปแบบการประทับเวลา: เมื่ออ้างอิงถึงช่วงเวลาที่เฉพาะเจาะจงในวิดีโอภายในพรอมต์ ให้ใช้รูปแบบ MM:SS (เช่น 01:15 สำหรับ 1 นาที 15 วินาที)
  • ตำแหน่งพรอมต์: หากรวมข้อความและวิดีโอเดียว ให้วางพรอมต์ข้อความหลังส่วนวิดีโอในอาร์เรย์ contents
  • การหมดเวลาสำหรับคำขอที่ใช้เวลานาน: สำหรับวิดีโอที่ต้องใช้เวลาประมวลผลนานขึ้นหรือการให้เหตุผลหลายขั้นตอนที่ซับซ้อน ให้ใช้การสตรีม (client.models.generate_content_stream) คำขอแบบซิงโครนัสที่ไม่ใช่การสตรีมซึ่งมีการลองใหม่ที่แบ็กเอนด์ภายใต้ดีมานด์สูงอาจเกินหน้าต่างความถูกต้องของการเชื่อมต่อหรือโทเค็นการตรวจสอบสิทธิ์ ซึ่งอาจปรากฏเป็นข้อผิดพลาด 401 Unauthorized หรือข้อผิดพลาดการหมดเวลาที่ไม่คาดคิด การสตรีมจะทำให้การเชื่อมต่อยังคงใช้งานได้และแสดงการให้เหตุผลระดับกลางและความคืบหน้าในการเรียกใช้เครื่องมือ

ขั้นตอนถัดไป

  • ความละเอียดของสื่อ: ควบคุม ความละเอียดของเฟรมวิดีโอเพื่อปรับสมดุลคุณภาพและการใช้โทเค็น
  • โทเค็น: ทำความเข้าใจวิธีแปลงเนื้อหาวิดีโอเป็นโทเค็น ในโหมดการประมวลผลแบบคงที่และแบบเอเจนต์
  • คำสั่งของระบบ: คำสั่งของระบบช่วยให้คุณกำหนดลักษณะการทำงานของโมเดลตามความต้องการ และกรณีการใช้งานที่เฉพาะเจาะจงได้
  • Files API: ดูข้อมูลเพิ่มเติมเกี่ยวกับการอัปโหลดและจัดการ ไฟล์เพื่อใช้กับ Gemini
  • กลยุทธ์การเขียนพรอมต์ไฟล์: Gemini API รองรับการเขียนพรอมต์ด้วยข้อมูลข้อความ รูปภาพ เสียง และวิดีโอ หรือที่เรียกว่าการเขียนพรอมต์แบบหลายรูปแบบ
  • คำแนะนำด้านความปลอดภัย: บางครั้งโมเดล Generative AI อาจสร้างเอาต์พุตที่ไม่คาดคิด เช่น เอาต์พุตที่ไม่ถูกต้อง มีอคติ หรือไม่เหมาะสม การประมวลผลภายหลังและการประเมินจากเจ้าหน้าที่เป็นสิ่งจำเป็นเพื่อ จำกัดความเสี่ยงที่จะเกิดอันตรายจากเอาต์พุตดังกล่าว