Interactions API の一般提供を開始しました。この API を使用して、最新の機能とモデルにアクセスすることをおすすめします。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

動画理解

ビデオ生成について学ぶには、Gemini Omni Flash ガイドを参照してください。

Gemini モデルは動画を処理できるため、従来はドメイン固有のモデルが必要だった多くの最先端開発者のユースケースに対応できます。 Gemini の画像処理機能には、動画の説明、セグメント化、情報抽出、動画コンテンツに関する質問への回答、動画内の特定のタイムスタンプの参照などが含まれます。

Gemini への入力として動画を提供する方法は以下のとおりです。

入力方法	最大サイズ	おすすめの使用例
ファイル API	20GB（有料）／2GB（無料）	大容量ファイル（100MB 以上）、長尺動画（10 分以上）、再利用可能なファイル。
クラウドストレージ登録	2GB（ファイルあたり、ストレージ容量制限なし）	大容量ファイル（100MB 以上）、長尺動画（10 分以上）、永続的で再利用可能なファイル。
インラインデータ	100MB 未満	ファイルサイズが小さい（100MB 未満）、処理時間が短い（1 分未満）、一度限りの入力。
YouTube URL	なし	公開されている YouTube 動画。

注: File APIは、ほとんどのユースケース、特に 100MB を超えるファイルや、複数のリクエストでファイルを再利用したい場合に推奨されます。

外部 URL や Google Cloud に保存されているファイルを使用するなど、その他のファイル入力方法については、ファイル入力方法ガイドを参照してください。

動画ファイルをアップロードする

以下のコードはサンプルビデオをダウンロードし、Files APIを使用してアップロードし、処理されるまで待機し、アップロードされたファイル参照を使用してビデオを要約します。

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

リクエストの合計サイズ（ファイル、テキストプロンプト、システム指示などを含む）が 20MB を超える場合、ビデオの長さが長い場合、または同じビデオを複数のプロンプトで使用する予定がある場合は、必ず Files API を使用してください。ファイル API は、ビデオファイル形式を直接受け付けます。

メディアファイルの操作の詳細については、Files API をご覧ください。

動画データをインラインで渡す

File API を使用して動画ファイルをアップロードする代わりに、より小さな動画ファイルをリクエストに直接渡すことができます。これは、合計リクエストサイズが 20MB 以下の短い動画に適しています。

インラインビデオデータを提供する例を以下に示します。

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

YouTube の URL を渡す

YouTube の URL をリクエストの一部として Gemini API に直接渡すには、次のようにします。

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

制限事項:

無料プランでは、1 日にアップロードできる YouTube 動画の時間は 8 時間までです。
有料プランの場合、動画の長さによる制限はありません。
Gemini 2.5 より前のモデルの場合、リクエストごとにアップロードできる動画は 1 本のみです。Gemini 2.5 以降のモデルでは、1 回のリクエストにつき最大 10 本の動画をアップロードできます。
公開動画のみアップロード可能です（非公開動画や限定公開動画はアップロードできません）。

エージェント型動画理解

デフォルトでは、ビデオ入力は静的処理（1 FPS でフレームを抽出）を使用します。 Gemini 3.8 Flash、3.7 Flash、3.6 Flash、3.5 Flash Lite モデルは、エージェント型の動画理解もサポートしています。この機能では、モデルが動画のタイムラインを動的に探索し、トランスクリプトを選択的に検査し、プロンプトに基づいてフレームレートと解像度を適応的に調整します。

Mode	説明	サポートされているモデル
静的（デフォルト）	一定レート（1 FPS）でフレームを抽出し、一度の処理でそれらを適切なコンテキストに配置します。短い動画には最適です。	全てのジェミニモデル
エージェント型	モデルは動画のタイムラインを動的に移動し、プロンプトに基づいて必要なコンテンツのみを読み込みます。トークン効率が最大 88% 向上し、長文コンテンツの品質が約 7% 向上します。	Gemini 3.8 Flash、3.7 Flash、3.6 Flash、3.5 Flash Lite

処理モードを選択する

一般的なガイドラインとして、特にレスポンスの品質やトークンの効率性を最適化する場合は、エージェント モードから始めることをおすすめします。

エージェント: 特定の瞬間をターゲットとする長編動画またはクエリ。このモデルは、コンテキストウィンドウを埋め尽くすことなく、文脈的に関連性の高い情報をターゲットとするために、タイムラインを動的にナビゲートします。
静的: 短いクリップ（5 分未満）に対するレイテンシの影響を受けやすいクエリ、またはクリップ全体でフレームレベルの精度が必要な場合。

注: エージェント処理に時間がかかる長いビデオや複雑なプロンプトの場合は、ストリーミング (stream=True) またはバックグラウンド実行 (background=True) を使用してください。これにより、接続がアクティブに維持され、中間推論ステップが表示され、接続タイムアウトや認証タイムアウトが回避されます。

処理モードを設定する

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

注: エージェント処理が使用されたことを確認するには、interaction.steps を調べます。processing_callとprocessing_resultが存在することは、モデルがビデオを動的にナビゲートしたことを示しています。

対応手順

エージェント処理により、steps配列に 2 つの新しいステップタイプが追加されます。

processing_call: モデルは、id で識別されるビデオセグメントまたは音声トランスクリプトを要求しました。
processing_result: call_id によってリンクされた、その負荷の結果。

これらは（要約が有効になっている場合）thoughtステップと交互に表示され、最後のmodel_outputステップの前に表示されます。これらは UI 上で進捗状況を表示するために使用できますが、応答は必要ありません。

以下の例は、処理ステップがインターリーブされた応答ペイロードを示しています。

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

動画間で処理モードを混在させる

同じリクエスト内で、動画ごとに異なる処理モードを設定できます。

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

複数ターンのビデオ会話

会話のやり取りを跨いでも、動画の文脈は保持される。エージェント処理を使用する場合：

ステートフルモード（previous_interaction_idを使用）：サーバーはビデオコンテキストを保持します。追加の処理は必要ありません。
ステートレスモード（step_listを使用）：ステートレスモードでは、レスポンスにはビデオコンテキストをエンコードするprocessing_callおよびprocessing_resultステップが含まれます。ビデオのコンテキストを保持するため、次のリクエストの step_list には、レスポンスに含まれるすべてのステップを含める必要があります。現在、これらを省略しても API エラーは発生しませんが、動画のコンテキストが失われるため、その後の質問に対する回答の質が著しく低下します。後続のリクエストで返されるステップも、入力トークン数に加算されることに注意してください。

コンテンツ内のタイムスタンプを参照する

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?"

動画から詳細な分析情報を抽出する

Gemini モデルは、音声と映像の両方のストリームから情報を処理することで、動画コンテンツを理解する強力な機能を提供します。これにより、動画で何が起こっているかの説明を生成したり、動画の内容に関する質問に回答したりするなど、詳細な情報を抽出できます。

視覚的な説明のために、モデルはビデオを毎秒1 フレーム（FPS）のレートでサンプリングします。このデフォルトのサンプリングレートはほとんどのコンテンツに適していますが、動きの速い動画や場面転換が速い動画では、細部が捉えきれない場合があることに注意してください。

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

動画処理をカスタマイズする

Gemini API では、クリッピング間隔を設定したり、カスタムフレームレートサンプリングを提供したりすることで、ビデオ処理をカスタマイズできます。これらのカスタマイズオプションは、"static"モードでビデオを処理する場合にのみサポートされます。

クリッピング間隔を設定する

processing 設定オブジェクトで start_offset と end_offset を指定することで、ビデオをクリップできます。

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

カスタムフレームレートを設定する

processing 設定オブジェクトに fps 引数を渡すことで、カスタムフレームレートサンプリングを設定できます。

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

サポートされている動画形式

Gemini は以下のビデオフォーマットの MIME タイプをサポートしています。

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

動画に関する技術的な詳細

サポートされているモデルとコンテキスト: すべての Gemini モデルはビデオデータを処理できます。
- コンテキストウィンドウが 1M のモデルは、デフォルトでは最大 3 時間（低解像度の場合）、高解像度の場合は最大 1 時間の長さの動画を処理できます。
処理モード: Gemini 3.8 Flash、3.7 Flash、3.6 Flash、3.5 Flash Lite、およびそれ以降のモデルは、2 つのビデオ処理モードをサポートしています:
- Static: フレームは 1 FPS で抽出され、コンテキストに配置されます (すべてのモデルのデフォルト)。音声は 1Kbps（シングルチャンネル）で処理されます。タイムスタンプは毎秒追加されます。短い動画クリップや、すべてのフレームが重要な場合（例えば、フレームごとの検査など）に最適です。1 FPS のサンプリングレートのため、動きの速いシーンではディテールが失われる可能性があることに注意してください。
- Agentic: モデルはビデオを動的にナビゲートし、必要に応じてトランスクリプト、フレーム、および/またはオーディオを読み込みます。これにより、長尺コンテンツで使用するトークン数を最大 88%削減できますが、生成開始前の内部推論とツール間の往復処理のため、短いクリップ（5 分未満）ではナビゲーションによって最初のトークン取得までの時間（TTFT）がわずかに増加する場合があります。トークンコストとレスポンス品質を最適化するには、長尺動画に最適です。 Gemini 3.8 Flash、3.7 Flash、3.6 Flash、および 3.5 Flash Lite に対応しています。詳細については、エージェントビデオの理解を参照してください。
トークン計算（静的モード）：ビデオの各秒は次のようにトークン化されます：
- 個々のフレーム（1 FPS でサンプリング）：
  - media_resolution が low に設定されている場合、フレームは 1 フレームあたり 66 トークンでトークン化されます。
  - それ以外の場合は、フレームは 1 フレームあたり 258 トークンでトークン化されます。
- 音声：毎秒 32 トークン。
- メタデータも含まれます。
- 合計：デフォルト（低）解像度の動画では 1 秒あたり約 100 トークン、高解像度の動画では 1 秒あたり約 300 トークン。
トークン計算（エージェントモード）：トークンの使用量は、コンテンツの複雑さとモデルのナビゲーション戦略によって異なります。動画探索中に生成されるナビゲーション推論トークンは、思考トークン (total_thought_tokens) としてカウントされ、オンデマンドでロードされるフレーム、オーディオ、およびトランスクリプトは、ツール使用トークン (total_tool_use_tokens) としてカウントされます。エージェント処理は、プロンプトに答えるために必要なトランスクリプト、フレーム、および/またはオーディオのみをロードするため、通常、長尺コンテンツの場合、静的処理よりも総トークン数が最大 88% 少なくなります (トークンガイドを参照)。
メディア解像度: Gemini 3 はmedia_resolutionパラメータを使用してマルチモーダルビジョン処理のきめ細かな制御を導入します。のmedia_resolutionパラメータは入力画像または動画フレームごとに割り当てられるトークンの最大数。 解像度を高くすると、モデルが細かい文字を読み取ったり、小さな詳細を識別したりする能力は向上しますが、トークンの使用量とレイテンシが増加します。media_resolutionとprocessingのパラメータは独立しています。同じビデオ入力に対して両方を設定できます。

トークン計算の詳細については、tokens ガイドを参照してください。

タイムスタンプ形式: プロンプト内でビデオの特定の瞬間を参照する場合は、MM:SS形式を使用します（例：1 分 15 秒の場合は01:15）。
プロンプトの配置: テキストと 1 つの動画を組み合わせる場合は、input 配列の動画部分の後にテキストプロンプトを配置します。
長時間のリクエストのタイムアウト: 処理に時間がかかる動画や、複雑なマルチステップの推論が必要な動画には、ストリーミング（stream=True）またはバックグラウンド実行（background=True）を使用します。需要が高いときにバックエンドで再試行が行われる同期の非ストリーミングリクエストは、接続または認証トークンの有効期間を超えることがあります。その場合、予期しない 401 Unauthorized エラーやタイムアウトエラーが発生することがあります。ストリーミングにより、接続がアクティブな状態が維持され、中間推論とツール呼び出しの進行状況が表示されます。

次のステップ

メディアの解像度: 動画フレームの解像度を制御して、品質とトークンの使用量のバランスを取ります。
トークン: 静的処理モードとエージェント処理モードの両方で、動画コンテンツがどのようにトークン化されるかを理解します。
システム指示: システム指示を使用すると、特定のニーズやユースケースに基づいてモデルの動作を制御できます。
Files API: Gemini で使用するファイルのアップロードと管理について説明します。
ファイルプロンプト戦略: Gemini API は、テキスト、画像、音声、動画データを使用したプロンプト（マルチモーダルプロンプトとも呼ばれます）をサポートしています。
安全に関するガイダンス: 生成 AI モデルは、不正確、偏見がある、不快な出力など、予期しない出力を生成することがあります。このような出力による危害のリスクを軽減するには、後処理と人間による評価が不可欠です。

動画理解

動画ファイルをアップロードする

Python

JavaScript

Java

REST

動画データをインラインで渡す

Python

JavaScript

Java

REST

YouTube の URL を渡す

Python

JavaScript

Java

REST

エージェント型動画理解

処理モードを選択する

処理モードを設定する

Python

JavaScript

REST

対応手順

動画間で処理モードを混在させる

Python

JavaScript

REST

複数ターンのビデオ会話

コンテンツ内のタイムスタンプを参照する

Python

JavaScript

Java

REST

動画から詳細な分析情報を抽出する

Python

JavaScript

Java

REST

動画処理をカスタマイズする

クリッピング間隔を設定する

Python

JavaScript

REST

カスタム フレームレートを設定する

Python

JavaScript

REST

サポートされている動画形式

動画に関する技術的な詳細

次のステップ

カスタムフレームレートを設定する