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

ดูข้อมูลเกี่ยวกับการสร้างวิดีโอได้ที่คู่มือ Gemini Omni Flash

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

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

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

หมายเหตุ: เราขอแนะนำให้ใช้ File API สำหรับกรณีการใช้งานส่วนใหญ่ โดยเฉพาะอย่างยิ่งสำหรับไฟล์ที่มีขนาดใหญ่กว่า 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

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

ใช้ 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 4 โมเดล Gemini 4 Argon, 3.8 Flash, 3.6 Flash และ 3.5 Flash Lite ยังรองรับ การทำความเข้าใจวิดีโอแบบเป็น Agent ซึ่งเป็นโหมดเลือกใช้ที่โมเดลจะสำรวจไทม์ไลน์วิดีโอ แบบไดนามิก ตรวจสอบคำบรรยายอย่างเลือกสรร และปรับอัตราเฟรม และความละเอียดแบบปรับเปลี่ยนได้ทันทีตามพรอมต์

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

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

เลือกโหมดการประมวลผลที่ตรงกับความยาววิดีโอและประเภทคําค้นหา

  • คงที่ (ค่าเริ่มต้น): เหมาะที่สุดสำหรับคลิปสั้นๆ (ไม่เกิน 5 นาที), สรุปวิดีโอแบบกว้างๆ ที่การบันทึกทั้งหมดมีความเกี่ยวข้อง, คำค้นหาที่ไวต่อเวลาในการตอบสนอง หรือความแม่นยำระดับเฟรมตลอดทั้งคลิป ในการประมวลผลแบบคงที่สำหรับวิดีโอสั้นๆ หรือพรอมต์แบบกว้างๆ ที่ต้องตรวจสอบวิดีโอส่วนใหญ่ จะไม่มีโทเค็นการคิดเพิ่มเติม (thoughts_token_count) และการเรียกใช้เครื่องมือแบบไปกลับ (tool_use_prompt_token_count) ที่เกิดจากการนำทางไทม์ไลน์
  • เป็น Agent: เหมาะที่สุดสำหรับวิดีโอแบบยาว (มากกว่า 5-10 นาที), การดึงข้อมูลที่ต้องการจากข้อมูลจำนวนมาก หรือคำค้นหาที่กำหนดเป้าหมายไปยังช่วงเวลาหรือหัวข้อที่เฉพาะเจาะจง โมเดลจะตรวจสอบคำบรรยายก่อนและโหลดเฉพาะส่วนภาพที่เกี่ยวข้องตามความต้องการ ซึ่งจะช่วยลดการใช้โทเค็นอินพุตวิดีโอได้สูงสุด 88% โดยไม่ทำให้หน้าต่างบริบทเต็ม

หมายเหตุ: สำหรับวิดีโอความยาวมากหรือพรอมต์ที่ซับซ้อนซึ่งการประมวลผลแบบเป็น Agent ใช้เวลานานขึ้น ให้ใช้การสตรีม (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?"}
      ]
    }]
  }'

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

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

โครงสร้างคำตอบ

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

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

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

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