Interactions API hiện đã được phát hành rộng rãi. Bạn nên sử dụng API này để truy cập vào tất cả các tính năng và mô hình mới nhất.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Hiểu video

Để tìm hiểu về tính năng tạo video, hãy xem hướng dẫn về Gemini Omni Flash.

Các mô hình Gemini có thể xử lý video, cho phép nhiều trường hợp sử dụng của nhà phát triển tiên phong mà trước đây cần đến các mô hình dành riêng cho miền. Một số khả năng thị giác của Gemini bao gồm: mô tả, phân đoạn và trích xuất thông tin từ video, trả lời câu hỏi về nội dung video và tham khảo các dấu thời gian cụ thể trong video.

Bạn có thể cung cấp video làm dữ liệu đầu vào cho Gemini theo những cách sau:

Phương thức nhập	Kích thước tối đa	Trường hợp sử dụng được đề xuất
File API	20 GB (có tính phí) / 2 GB (miễn phí)	Tệp lớn (từ 100 MB trở lên), video dài (từ 10 phút trở lên), tệp có thể dùng lại.
Đăng ký Cloud Storage	2 GB (mỗi tệp, không giới hạn bộ nhớ)	Tệp lớn (từ 100 MB trở lên), video dài (từ 10 phút trở lên), tệp có thể dùng lại và lưu trữ lâu dài.
Dữ liệu nội tuyến	< 100MB	Tệp nhỏ (<100 MB), thời lượng ngắn (<1 phút), dữ liệu đầu vào một lần.
URL trên YouTube	Không áp dụng	Video công khai trên YouTube.

Lưu ý: Bạn nên dùng File API cho hầu hết các trường hợp sử dụng, đặc biệt là đối với những tệp có kích thước lớn hơn 100 MB hoặc khi bạn muốn dùng lại tệp trong nhiều yêu cầu.

Để tìm hiểu về các phương thức nhập tệp khác, chẳng hạn như sử dụng URL bên ngoài hoặc tệp được lưu trữ trong Google Cloud, hãy xem hướng dẫn Phương thức nhập tệp.

Tải tệp video lên

Đoạn mã sau đây tải một video mẫu xuống, tải video đó lên bằng Files API, đợi video được xử lý, sau đó dùng thông tin tham chiếu về tệp đã tải lên để tóm tắt video.

Python

from google import genai
import time

client = genai.Client()

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

while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "video", "uri": myfile.uri, "mime_type": myfile.mime_type},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
    ]
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } 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" },
  });

  let getFile = await ai.files.get({ name: myfile.name });
  while (getFile.state === 'PROCESSING') {
      getFile = await ai.files.get({ name: myfile.name });
      console.log(`current file status: ${getFile.state}`);
      console.log('File is still processing, retrying in 5 seconds');

      await new Promise((resolve) => {
          setTimeout(resolve, 5000);
      });
  }
  if (getFile.state === 'FAILED') {
      throw new Error('File processing failed.');
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "video", uri: myfile.uri, mime_type: myfile.mimeType },
      { type: "text", text: "Summarize this video. Then create a quiz with an answer key based on the information in this video." }
    ],
  });
  console.log(interaction.output_text);
}

await main();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

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)
file_name=$(jq -r ".file.name" file_info.json)
echo file_uri=$file_uri

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

# Polling loop
echo "Waiting for file to be processed..."
while true; do
  curl -s "https://generativelanguage.googleapis.com/v1beta/${file_name}" \
    -H "x-goog-api-key: $GEMINI_API_KEY" > file_status.json
  state=$(jq -r ".state" file_status.json)
  echo "Current state: $state"
  if [ "$state" == "ACTIVE" ]; then
    break
  elif [ "$state" == "FAILED" ]; then
    echo "File processing failed."
    exit 1
  fi
  sleep 5
done

echo "Generating content from video..."
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "video", "uri": "'${file_uri}'", "mime_type": "'${MIME_TYPE}'"},
        {"type": "text", "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 ".steps[].content[0].text" response.json

Luôn sử dụng API Tệp khi tổng kích thước yêu cầu (bao gồm tệp, lời nhắc văn bản, hướng dẫn hệ thống, v.v.) lớn hơn 20 MB, thời lượng video đáng kể hoặc nếu bạn dự định sử dụng cùng một video trong nhiều lời nhắc khác nhau. API Tệp chấp nhận trực tiếp các định dạng tệp video.

Để tìm hiểu thêm về cách làm việc với các tệp nội dung nghe nhìn, hãy xem Files API.

Truyền dữ liệu video trực tiếp

Thay vì tải lên tệp video bằng API Tệp, bạn có thể truyền trực tiếp các video có dung lượng nhỏ hơn trong yêu cầu. Phương pháp này phù hợp với các video ngắn có tổng dung lượng yêu cầu dưới 20MB.

Đây là một ví dụ về việc cung cấp dữ liệu video trực tiếp:

Python

from google import genai
import base64

video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "data": base64.b64encode(video_bytes).decode('utf-8'),
            "mime_type": "video/mp4"
        }
    ]
)
print(interaction.output_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 interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      data: base64VideoFile,
      mime_type: "video/mp4",
    }
  ],
});
console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

REST

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

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

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

Truyền URL YouTube

Bạn có thể truyền trực tiếp URL YouTube đến API của Gemini như một phần của yêu cầu như sau:

Python

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
    ]
)
print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      uri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    }
  ],
});
console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

REST

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

Giới hạn:

Với gói miễn phí, bạn không thể tải lên quá 8 giờ video YouTube mỗi ngày.
Đối với gói trả phí, không có giới hạn nào về độ dài video.
Đối với các mẫu máy trước Gemini 2.5, bạn chỉ có thể tải lên 1 video cho mỗi yêu cầu. Đối với Gemini 2.5 trở lên, bạn có thể tải lên tối đa 10 video cho mỗi yêu cầu.
Bạn chỉ có thể tải lên các video công khai (không phải video riêng tư hoặc không được liệt kê).

Tính năng hiểu video dựa trên tác nhân

Theo mặc định, đầu vào video sử dụng quy trình xử lý tĩnh (trích xuất khung hình ở tốc độ 1 khung hình/giây). Các mô hình Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash và 3.5 Flash Lite cũng hỗ trợ khả năng hiểu video dựa trên tác nhân, trong đó mô hình này sẽ khám phá dòng thời gian của video một cách linh hoạt, chọn lọc nội dung để kiểm tra bản chép lời và điều chỉnh tốc độ khung hình cũng như độ phân giải một cách linh hoạt ngay lập tức dựa trên câu lệnh.

Chế độ	Nội dung mô tả	Các mẫu được hỗ trợ
Tĩnh (mặc định)	Trích xuất các khung hình ở tốc độ cố định (1 khung hình/giây) và đặt chúng vào ngữ cảnh trong một lượt. Phù hợp với các đoạn video ngắn.	Tất cả các mô hình Gemini
Tác nhân	Mô hình này điều hướng dòng thời gian của video một cách linh hoạt, chỉ tải nội dung cần thiết dựa trên câu lệnh. Hiệu quả hơn tới 88% về mã thông báo và chất lượng cao hơn khoảng 7% đối với nội dung dạng dài.	Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite

Chọn một chế độ xử lý

Theo nguyên tắc chung, hãy bắt đầu với chế độ có tác nhân, đặc biệt là khi tối ưu hoá để có chất lượng phản hồi hoặc hiệu quả sử dụng mã thông báo.

Dựa trên tác nhân: Video dài hoặc cụm từ tìm kiếm nhắm đến những khoảnh khắc cụ thể. Mô hình này điều hướng dòng thời gian một cách linh hoạt để nhắm đến thông tin phù hợp theo ngữ cảnh mà không cần điền vào cửa sổ ngữ cảnh.
Tĩnh: Các truy vấn nhạy cảm với độ trễ trên các đoạn video ngắn (dưới 5 phút) hoặc các trường hợp cần độ chính xác ở cấp khung hình trên toàn bộ đoạn video.

Lưu ý: Đối với những video dài hoặc câu lệnh phức tạp mà quá trình xử lý dựa trên tác nhân mất nhiều thời gian hơn, hãy sử dụng tính năng phát trực tuyến (stream=True) hoặc thực thi ở chế độ nền (background=True). Điều này giúp duy trì kết nối, hiển thị các bước lập luận trung gian và tránh hết thời gian chờ kết nối hoặc xác thực.

Đặt chế độ xử lý

Python

import time
from google import genai

client = genai.Client()

# Upload a long video
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)

# Use agentic processing
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": "agentic"
        },
        {"type": "text", "text": "What are the three main arguments presented?"}
    ]
)
print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

// Upload a long video
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 });
}

// Use agentic processing
const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: "agentic"
    },
    { type: "text", text: "What are the three main arguments presented?" }
  ]
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {"type": "text", "text": "What are the three main arguments presented?"}
    ]
  }' 2> /dev/null

Lưu ý: Để xác minh rằng quá trình xử lý dựa trên tác nhân đã được sử dụng, hãy kiểm tra interaction.steps. Sự xuất hiện của processing_call và processing_result cho biết mô hình đã điều hướng video một cách linh động.

Các bước phản hồi

Quá trình xử lý tác nhân bổ sung hai loại bước mới vào mảng steps:

processing_call: mô hình yêu cầu một đoạn video hoặc bản ghi âm, được xác định bởi id.
processing_result: kết quả của quá trình tải đó, được liên kết bởi call_id.

Những bước này xuất hiện xen kẽ với các bước thought (khi chức năng tóm tắt được bật) và đứng trước bước model_output cuối cùng. Chúng có thể được sử dụng để hiển thị tiến trình trong giao diện người dùng của bạn nhưng không yêu cầu phản hồi.

Ví dụ sau đây minh họa dữ liệu phản hồi với các bước xử lý xen kẽ:

{
  "steps": [
    {
      "type": "thought",
      "signature": "sig_thought_1",
      "summary": [
        {
          "type": "text",
          "text": "Inspecting transcript for key discussion topics..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_01",
      "signature": "sig_call_01"
    },
    {
      "type": "processing_result",
      "call_id": "call_01",
      "signature": "sig_result_01"
    },
    {
      "type": "thought",
      "signature": "sig_thought_2",
      "summary": [
        {
          "type": "text",
          "text": "Loading visual frames to verify slide content..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_02",
      "signature": "sig_call_02"
    },
    {
      "type": "processing_result",
      "call_id": "call_02",
      "signature": "sig_result_02"
    },
    {
      "type": "thought",
      "signature": "sig_thought_3",
      "summary": [
        {
          "type": "text",
          "text": "Synthesizing answer from gathered evidence..."
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The three main arguments presented in the lecture are..."
        }
      ]
    }
  ]
}

Kết hợp các chế độ xử lý trên nhiều video

Bạn có thể thiết lập các chế độ xử lý khác nhau cho từng video trong cùng một yêu cầu:

Python

from google import genai

client = genai.Client()

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

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": lecture.uri,
            "mime_type": lecture.mime_type,
            "processing": "agentic"  # Use agentic video understanding
        },
        {
            "type": "video",
            "uri": experiment.uri,
            "mime_type": experiment.mime_type,
            "processing": "static"  # Use static processing
        },
        {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ]
)
print(interaction.output_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 interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: lecture.uri,
      mime_type: lecture.mimeType,
      processing: "agentic" // Use agentic video understanding
    },
    {
      type: "video",
      uri: experiment.uri,
      mime_type: experiment.mimeType,
      processing: "static" // Use static processing
    },
    { type: "text", text: "Compare the lecture content with the experiment results." }
  ]
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${lecture_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {
        "type": "video",
        "uri": "'${experiment_uri}'",
        "mime_type": "video/mp4",
        "processing": "static"
      },
      {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ]
  }' 2> /dev/null

Cuộc trò chuyện video nhiều lượt

Ngữ cảnh video được giữ nguyên xuyên suốt các lượt hội thoại. Khi sử dụng xử lý tác nhân:

Chế độ trạng thái (sử dụng previous_interaction_id): Máy chủ giữ lại ngữ cảnh video. Không cần thao tác thêm nào nữa.
Chế độ không trạng thái (sử dụng step_list): Ở chế độ không trạng thái, phản hồi bao gồm các bước processing_call và processing_result mã hóa ngữ cảnh video. Bạn phải bao gồm tất cả các bước từ phản hồi trong yêu cầu tiếp theo của mình step_list để giữ nguyên ngữ cảnh video. Mặc dù việc bỏ qua chúng hiện không gây ra lỗi API, nhưng ngữ cảnh video sẽ bị mất, làm giảm đáng kể chất lượng phản hồi cho các câu hỏi tiếp theo. Lưu ý rằng các bước được trả về trong các yêu cầu tiếp theo sẽ góp phần vào số lượng mã thông báo đầu vào.

Vui lòng tham khảo mốc thời gian trong nội dung.

Bạn có thể đặt câu hỏi về những mốc thời gian cụ thể trong video bằng cách sử dụng dấu thời gian có dạng MM:SS.

Python

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

JavaScript

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

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

REST

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

Trích xuất thông tin chi tiết từ video

Các mẫu Gemini cung cấp khả năng mạnh mẽ trong việc hiểu nội dung video bằng cách xử lý thông tin từ cả hai nguồn.âm thanh và hình ảnh dòng chảy. Điều này cho phép bạn trích xuất một tập hợp thông tin chi tiết phong phú, bao gồm việc tạo mô tả về những gì đang diễn ra trong video và trả lời các câu hỏi về nội dung của video đó.

Để mô tả trực quan, mô hình lấy mẫu video với tốc độ 1 khung hình mỗi giây (FPS). Tốc độ lấy mẫu mặc định này hoạt động tốt với hầu hết các nội dung, nhưng lưu ý rằng nó có thể bỏ sót chi tiết trong các video có chuyển động nhanh hoặc thay đổi cảnh đột ngột.

Python

prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

JavaScript

const prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.";

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

REST

PROMPT="Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

Tùy chỉnh xử lý video

Bạn có thể tùy chỉnh quá trình xử lý video trong API Gemini bằng cách thiết lập khoảng thời gian cắt xén hoặc cung cấp tốc độ lấy mẫu khung hình tùy chỉnh. Các tùy chọn tùy chỉnh này chỉ được hỗ trợ khi xử lý video ở chế độ "static".

Đặt khoảng thời gian cắt

Bạn có thể cắt video bằng cách chỉ định start_offset và end_offset trong đối tượng cấu hình processing.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "start_offset": 1200,
                "end_offset": 1500,
            },
        },
        {"type": "text", "text": "Summarize this section of the video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        start_offset: 1200,
        end_offset: 1500,
      },
    },
    { type: "text", text: "Summarize this section of the video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "start_offset": 1200,
          "end_offset": 1500
        }
      },
      {"type": "text", "text": "Summarize this section of the video."}
    ]
  }' 2> /dev/null

Đặt tốc độ khung hình tùy chỉnh

Bạn có thể thiết lập tốc độ lấy mẫu khung hình tùy chỉnh bằng cách truyền đối số fps vào đối tượng cấu hình processing.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "fps": 0.5,  # Sample 1 frame every 2 seconds
            },
        },
        {"type": "text", "text": "Describe the scene changes in this video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        fps: 0.5, // Sample 1 frame every 2 seconds
      },
    },
    { type: "text", text: "Describe the scene changes in this video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "fps": 0.5
        }
      },
      {"type": "text", "text": "Describe the scene changes in this video."}
    ]
  }' 2> /dev/null

Các định dạng video được hỗ trợ

Gemini hỗ trợ các loại định dạng video MIME sau:

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

Thông tin kỹ thuật chi tiết về video

Các mẫu và ngữ cảnh được hỗ trợ: Tất cả các mẫu Gemini đều có thể xử lý dữ liệu video.
- Các mô hình với cửa sổ ngữ cảnh 1M có thể xử lý video dài tối đa 3 giờ theo mặc định (ở độ phân giải phương tiện thấp), hoặc tối đa 1 giờ ở độ phân giải phương tiện cao.
Chế độ xử lý: Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite và các mẫu sau này hỗ trợ hai chế độ xử lý video:
- Static: Các khung hình được trích xuất ở tốc độ 1 FPS và được đặt vào ngữ cảnh (mặc định cho tất cả các mô hình). Âm thanh được xử lý ở tốc độ 1Kbps (một kênh). Dấu thời gian được thêm vào mỗi giây. Thích hợp nhất cho các đoạn video ngắn hoặc khi mỗi khung hình đều quan trọng (chẳng hạn như kiểm tra từng khung hình một). Lưu ý rằng các cảnh hành động nhanh có thể bị mất chi tiết do tốc độ lấy mẫu 1 FPS.
- Agent: Mô hình tự động điều hướng video, tải bản ghi và/hoặc khung hình và/hoặc âm thanh theo yêu cầu. Phương pháp này sử dụng ít hơn tới 88% token cho nội dung dài, mặc dù việc điều hướng có thể làm tăng nhẹ Thời gian đến Token đầu tiên (TTFT) đối với các video ngắn (<5 phút) do quá trình xử lý nội bộ và các vòng lặp công cụ trước khi quá trình tạo bắt đầu. Tốt nhất nên dùng cho video dài để tối ưu hóa chi phí token và chất lượng phản hồi. Được hỗ trợ trên Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash và 3.5 Flash Lite. Xem Hiểu biết về video của tác nhân để biết thêm chi tiết.
Tính toán mã thông báo (chế độ tĩnh): Mỗi giây của video được mã hóa như sau:
- Các khung hình riêng lẻ (được lấy mẫu ở tốc độ 1 khung hình/giây):
  - Nếu media_resolution được đặt ở mức thấp, các khung hình sẽ được phân tách thành 66 token mỗi khung hình.
  - Ngược lại, các khung hình được phân tách thành 258 token mỗi khung hình.
- Âm thanh: 32 token mỗi giây.
- Siêu dữ liệu cũng được bao gồm.
- Tổng cộng: Khoảng 100 token mỗi giây video ở độ phân giải mặc định (thấp), hoặc khoảng 300 token mỗi giây video ở độ phân giải cao.
Tính toán mã thông báo (chế độ tác nhân): Việc sử dụng mã thông báo thay đổi tùy thuộc vào độ phức tạp của nội dung và chiến lược điều hướng của mô hình. Các token suy luận điều hướng được tạo ra trong quá trình khám phá video được tính là token suy nghĩ (total_thought_tokens), trong khi các khung hình, âm thanh và bản ghi được tải theo yêu cầu được tính là token sử dụng công cụ (total_tool_use_tokens). Quá trình xử lý tác nhân thường sử dụng ít hơn tới 88% tổng số token so với xử lý tĩnh đối với nội dung dài vì mô hình chỉ tải bản ghi và/hoặc khung hình và/hoặc âm thanh mà nó cần để trả lời lời nhắc (xem hướng dẫn về token).
Độ phân giải phương tiện: Gemini 3 giới thiệu khả năng kiểm soát chi tiết quá trình xử lý hình ảnh đa phương thức với tham số media_resolution. Tham số media_resolution xác định số lượng token tối đa được phân bổ cho mỗi hình ảnh hoặc khung hình video đầu vào. Độ phân giải cao hơn cải thiện khả năng đọc văn bản nhỏ hoặc nhận diện các chi tiết nhỏ của mô hình, nhưng làm tăng mức sử dụng token và độ trễ. Các tham số media_resolution và processing hoạt động độc lập: bạn có thể thiết lập cả hai trên cùng một đầu vào video.

Để biết thêm chi tiết về cách tính toán token, hãy xem hướng dẫn token.

Định dạng dấu thời gian: Khi đề cập đến những khoảnh khắc cụ thể trong video trong câu lệnh, hãy sử dụng định dạng MM:SS (ví dụ: 01:15 cho 1 phút 15 giây).
Vị trí của câu lệnh: Nếu kết hợp văn bản và một video, hãy đặt câu lệnh văn bản sau phần video trong mảng input.
Hết thời gian chờ đối với các yêu cầu dài: Đối với những video cần thời gian xử lý kéo dài hoặc lý luận phức tạp qua nhiều bước, hãy sử dụng tính năng phát trực tuyến (stream=True) hoặc thực thi dưới nền (background=True). Các yêu cầu đồng bộ, không phát trực tuyến gặp phải tình trạng thử lại phụ trợ trong điều kiện có nhu cầu cao có thể vượt quá thời gian hiệu lực của mã thông báo xác thực hoặc kết nối, điều này có thể xuất hiện dưới dạng lỗi 401 Unauthorized hoặc lỗi hết thời gian chờ không mong muốn. Tính năng truyền phát trực tiếp duy trì kết nối và hiển thị quá trình suy luận trung gian cũng như tiến trình gọi công cụ.

Bước tiếp theo

Độ phân giải của nội dung nghe nhìn: Kiểm soát độ phân giải của khung hình video để cân bằng chất lượng và mức sử dụng mã thông báo.
Mã thông báo: Tìm hiểu cách nội dung video được mã hoá ở cả chế độ xử lý tĩnh và chế độ xử lý dựa trên tác nhân.
Hướng dẫn hệ thống: Hướng dẫn hệ thống giúp bạn điều chỉnh hành vi của mô hình dựa trên nhu cầu và trường hợp sử dụng cụ thể của bạn.
Files API: Tìm hiểu thêm về cách tải lên và quản lý tệp để sử dụng với Gemini.
Chiến lược đặt câu lệnh cho tệp: Gemini API hỗ trợ đặt câu lệnh bằng dữ liệu văn bản, hình ảnh, âm thanh và video, còn được gọi là đặt câu lệnh đa phương thức.
Hướng dẫn về an toàn: Đôi khi, các mô hình AI tạo sinh tạo ra kết quả không mong muốn, chẳng hạn như kết quả không chính xác, thiên vị hoặc phản cảm. Hậu xử lý và đánh giá của con người là những yếu tố cần thiết để hạn chế nguy cơ gây hại từ những kết quả như vậy.