Gemini API で Veo 3 を利用できるようになりました。詳細

このページは Cloud Translation API によって翻訳されました。

動画理解

Gemini モデルは動画を処理できるため、これまでドメイン固有のモデルが必要だった多くの最先端のデベロッパーユースケースを実現できます。Gemini のビジョン機能には、次のようなものがあります。

動画の説明、セグメント化、情報の抽出
動画コンテンツに関する質問に回答する
動画内の特定のタイムスタンプを参照する

Gemini はマルチモーダルを念頭にゼロから構築されており、Google は可能性の限界を押し広げ続けています。このガイドでは、Gemini API を使用して動画入力に基づいてテキストレスポンスを生成する方法について説明します。

ビデオ入力

Gemini に動画を入力するには、次の方法があります。

generateContent にリクエストを行う前に、File API を使用して動画ファイルをアップロードします。このメソッドは、20 MB を超えるファイル、約 1 分を超える動画、または複数のリクエストでファイルを再利用する場合に使用します。
generateContent へのリクエストでインライン動画データを渡します。この方法は、ファイルサイズが小さく（20 MB 未満）、期間が短い場合に適しています。
YouTube の URL をプロンプトに直接含めます。

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

Files API を使用して、動画ファイルをアップロードできます。リクエストの合計サイズ（ファイル、テキストプロンプト、システム指示などを含む）が 20 MB を超える場合、動画の長さが長い場合、または複数のプロンプトで同じ動画を使用する場合は、常に Files API を使用します。File API は動画ファイル形式を直接受け入れます。

次のコードは、サンプル動画をダウンロードし、File API を使用してアップロードし、処理されるのを待ってから、generateContent リクエストでファイル参照を使用します。

Python

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-2.5-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-2.5-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-2.5-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-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data":{"mime_type": "'"${MIME_TYPE}"'", "file_uri": "'"${file_uri}"'"}},
          {"text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}]
        }]
      }' 2> /dev/null > response.json

jq -r ".candidates[].content.parts[].text" response.json

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

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

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

インライン動画データを提供する例を次に示します。

Python

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(data=video_bytes, mime_type='video/mp4')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const base64VideoFile = fs.readFileSync("path/to/small-sample.mp4", {
  encoding: "base64",
});

const contents = [
  {
    inlineData: {
      mimeType: "video/mp4",
      data: base64VideoFile,
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: contents,
});
console.log(response.text);

REST

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

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-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

YouTube の URL を含める

Gemini API と AI Studio は、YouTube の URL をファイルデータ Part としてサポートしています。モデルに動画コンテンツの要約、翻訳、その他の操作を求めるプロンプトに YouTube の URL を含めることができます。

制限事項:

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

次の例は、プロンプトに YouTube URL を含める方法を示しています。

Python

response = client.models.generate_content(
    model='models/gemini-2.5-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=9hE5-98ZeCg')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro" });
const result = await model.generateContent([
  "Please summarize the video in 3 sentences.",
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
]);
console.log(result.response.text());

Go

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-2.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-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

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

動画内の特定の時点について質問するには、MM:SS 形式のタイムスタンプを使用します。

Python

prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?" # Adjusted timestamps for the NASA video

JavaScript

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

Go

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
         // Adjusted timestamps for the NASA video
        genai.NewPartFromText("What are the examples given at 00:05 and " +
            "00:10 supposed to show us?"),
    }

REST

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

動画を文字起こしして視覚的な説明を提供する

Gemini モデルは、音声トラックと視覚フレームの両方を処理することで、動画コンテンツの文字起こしと視覚的な説明を提供できます。視覚的な説明の場合、モデルは 1 秒あたり 1 フレームのレートで動画をサンプリングします。このサンプリングレートは、説明の詳細レベルに影響する可能性があります。特に、映像が急速に変化する動画では影響が大きくなります。

Python

prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

JavaScript

const prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions.";

Go

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
        genai.NewPartFromText("Transcribe the audio from this video, giving timestamps for salient events in the video. Also " +
            "provide visual descriptions."),
    }

REST

PROMPT="Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

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

Gemini API で動画処理をカスタマイズするには、クリッピング間隔を設定するか、カスタムフレームレートサンプリングを指定します。

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

開始オフセットと終了オフセットを指定して videoMetadata を指定することで、動画をクリップできます。

Python

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

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

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

Python

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

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

デフォルトでは、動画から 1 秒あたり 1 フレーム（FPS）がサンプリングされます。長い動画の場合は、FPS を低く（1 未満）設定することをおすすめします。この機能は、ほとんど静止している動画（講義など）に特に役立ちます。急速に変化する映像の詳細をキャプチャする場合は、FPS の値を高く設定することを検討してください。

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

Gemini は、次の動画形式の MIME タイプをサポートしています。

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

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

サポートされているモデルとコンテキスト: すべての Gemini 2.0 モデルと 2.5 モデルで動画データを処理できます。
- 200 万個のコンテキストウィンドウを持つモデルは、デフォルトのメディア解像度で最大 2 時間、低メディア解像度で最大 6 時間の動画を処理できます。一方、100 万個のコンテキストウィンドウを持つモデルは、デフォルトのメディア解像度で最大 1 時間、低メディア解像度で最大 3 時間の動画を処理できます。
File API の処理: File API を使用する場合、動画は 1 秒あたり 1 フレーム（FPS）でサンプリングされ、音声は 1 Kbps（シングルチャンネル）で処理されます。タイムスタンプは 1 秒ごとに追加されます。
- これらのレートは、推論の改善のために今後変更される可能性があります。
トークンの計算: 動画の各秒は次のようにトークン化されます。
- 個々のフレーム（1 FPS でサンプリング）:
  - mediaResolution が低に設定されている場合、フレームはフレームあたり 66 個のトークンでトークン化されます。
  - それ以外の場合、フレームはフレームあたり 258 個のトークンでトークン化されます。
- 音声: 1 秒あたり 32 個のトークン。
- メタデータも含まれます。
- 合計: デフォルトのメディア解像度の場合、動画 1 秒あたり約 300 トークン。低解像度のメディアの場合、動画 1 秒あたり 100 トークン。
タイムスタンプの形式: プロンプト内で動画の特定の瞬間を参照する場合は、MM:SS 形式（例: 01:15（1 分 15 秒）。
ベストプラクティス:
- 最適な結果を得るには、プロンプトリクエストごとに 1 つの動画のみを使用します。
- テキストと 1 つの動画を組み合わせる場合は、contents 配列の動画部分の後にテキストプロンプトを配置します。
- 1 FPS のサンプリングレートでは、高速なアクションシーケンスの詳細が失われる可能性があります。必要に応じて、そのようなクリップの速度を遅くすることを検討してください。

次のステップ

このガイドでは、動画ファイルをアップロードし、動画入力からテキスト出力を生成する方法について説明します。詳細については、次のリソースをご覧ください。

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

動画理解

ビデオ入力

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

Python

JavaScript

Go

REST

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

Python

JavaScript

REST

YouTube の URL を含める

Python

JavaScript

Go

REST

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

Python

JavaScript

Go

REST

動画を文字起こしして視覚的な説明を提供する

Python

JavaScript

Go

REST

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

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

Python

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

Python

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

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

次のステップ

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