gemini-3-multimodal

Gemini 3 Pro マルチモーダル入力処理

Gemini 3 Pro を使用したマルチモーダル入力処理の包括的なガイドです。画像の理解、動画分析、音声処理、PDF ドキュメントの抽出を扱います。このスキルでは入力処理（メディアの分析）に焦点を当てています。出力（画像の生成）については、gemini-3-image-generation を参照してください。

概要

Gemini 3 Pro は、さまざまな種類のメディアを理解・分析するためのネイティブなマルチモーダル機能を備えています。このスキルでは、品質、パフォーマンス、トークン消費量をきめ細かく制御しながら、あらゆる入力処理を行う方法を説明します。

主な機能

• 画像の理解： 物体検出、OCR、視覚的な質疑応答、スクリーンショットからのコード生成
• 動画処理： 最大 1 時間の動画、フレーム分析、OCR
• 音声処理： 最大 9.5 時間の音声、音声の理解
• PDF ドキュメント： ネイティブな PDF サポート、複数ページの分析、テキスト抽出
• メディア解像度の制御： トークン最適化のための低・中・高解像度
• トークンの最適化： 処理コストをきめ細かく制御

このスキルを使用する場面

• 画像、写真、スクリーンショットを分析する
• 分析情報を得るために動画コンテンツを処理する
• 音声や発話を文字起こし、または理解する
• PDF ドキュメントから情報を抽出する
• マルチモーダルアプリケーションを構築する
• メディア処理コストを最適化する

---

クイックスタート

前提条件

• Gemini API のセットアップ（gemini-3-pro-api スキルを参照）
• サポートされている形式のメディアファイル

Python クイックスタート

import google.generativeai as genai
from pathlib import Path

genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel("gemini-3-pro-preview")

# Upload and analyze image
image_file = genai.upload_file(Path("photo.jpg"))
response = model.generate_content([
    "What's in this image?",
    image_file
])
print(response.text)

Node.js クイックスタート

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

const genAI = new GoogleGenerativeAI("YOUR_API_KEY");
const fileManager = new GoogleAIFileManager("YOUR_API_KEY");

// Upload and analyze image
const uploadResult = await fileManager.uploadFile("photo.jpg", {
  mimeType: "image/jpeg"
});

const model = genAI.getGenerativeModel({ model: "gemini-3-pro-preview" });
const result = await model.generateContent([
  "What's in this image?",
  { fileData: { fileUri: uploadResult.file.uri, mimeType: uploadResult.file.mimeType } }
]);

console.log(result.response.text());

---

主なタスク

タスク 1：画像コンテンツを分析する

目的： 画像から情報、物体、テキスト、分析情報を抽出します。

ユースケース：

• 物体の検出と認識
• OCR（画像からのテキスト抽出）
• 視覚的な質疑応答
• UI スクリーンショットからのコード生成
• グラフや図表の分析
• 製品の識別

Python の例：

import google.generativeai as genai
from pathlib import Path

genai.configure(api_key="YOUR_API_KEY")

# Configure model with high resolution for best quality
model = genai.GenerativeModel(
    "gemini-3-pro-preview",
    generation_config={
        "thinking_level": "high",
        "media_resolution": "high"  # 1,120 tokens per image
    }
)

# Upload image
image_path = Path("screenshot.png")
image_file = genai.upload_file(image_path)

# Analyze with specific prompt
response = model.generate_content([
    """Analyze this image and provide:
    1. Main objects and their locations
    2. Any visible text (OCR)
    3. Overall context and purpose
    4. If code/UI: describe the functionality
    """,
    image_file
])

print(response.text)

# Check token usage
print(f"Tokens used: {response.usage_metadata.total_token_count}")

Node.js の例：

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

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
const fileManager = new GoogleAIFileManager(process.env.GEMINI_API_KEY!);

// Upload image
const uploadResult = await fileManager.uploadFile("screenshot.png", {
  mimeType: "image/png"
});

// Configure model with high resolution
const model = genAI.getGenerativeModel({
  model: "gemini-3-pro-preview",
  generationConfig: {
    thinking_level: "high",
    media_resolution: "high"  // Best quality for OCR
  }
});

const result = await model.generateContent([
  `Analyze this image and provide:
  1. Main objects and their locations
  2. Any visible text (OCR)
  3. Overall context and purpose`,
  { fileData: { fileUri: uploadResult.file.uri, mimeType: uploadResult.file.mimeType } }
]);

console.log(result.response.text());

解像度の選択肢：

解像度	画像あたりのトークン数	適した用途
low	280 トークン	すばやい分析、細部の不要な処理
medium	560 トークン	品質とコストのバランス
high	1,120 トークン	OCR、細部、小さな文字

対応形式： JPEG、PNG、WEBP、HEIC、HEIF

参照： 高度なパターンについては references/image-understanding.md を参照してください。

---

タスク 2：動画コンテンツを処理する

目的： 動画コンテンツを分析し、分析情報を抽出して、フレーム単位の分析を行います。

ユースケース：

• 動画の要約
• 物体の追跡
• シーンの検出
• 動画 OCR
• コンテンツモデレーション
• 教育動画の分析

Python の例：

import google.generativeai as genai
from pathlib import Path

genai.configure(api_key="YOUR_API_KEY")

# Configure for video processing
model = genai.GenerativeModel(
    "gemini-3-pro-preview",
    generation_config={
        "thinking_level": "high",
        "media_resolution": "medium"  # 70 tokens/frame (balanced)
    }
)

# Upload video (up to 1 hour supported)
video_path = Path("tutorial.mp4")
video_file = genai.upload_file(video_path)

# Wait for processing
import time
while video_file.state.name == "PROCESSING":
    time.sleep(5)
    video_file = genai.get_file(video_file.name)

if video_file.state.name == "FAILED":
    raise ValueError("Video processing failed")

# Analyze video
response = model.generate_content([
    """Analyze this video and provide:
    1. Overall summary of content
    2. Key scenes and timestamps
    3. Main topics covered
    4. Any visible text throughout the video
    """,
    video_file
])

print(response.text)
print(f"Tokens used: {response.usage_metadata.total_token_count}")

Node.js の例：

import { GoogleGenerativeAI } from "@google/generative-ai";
import { GoogleAIFileManager, FileState } from "@google/generative-ai/server";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
const fileManager = new GoogleAIFileManager(process.env.GEMINI_API_KEY!);

// Upload video
const uploadResult = await fileManager.uploadFile("tutorial.mp4", {
  mimeType: "video/mp4"
});

// Wait for processing
let file = await fileManager.getFile(uploadResult.file.name);
while (file.state === FileState.PROCESSING) {
  await new Promise(resolve => setTimeout(resolve, 5000));
  file = await fileManager.getFile(uploadResult.file.name);
}

if (file.state === FileState.FAILED) {
  throw new Error("Video processing failed");
}

// Analyze video
const model = genAI.getGenerativeModel({
  model: "gemini-3-pro-preview",
  generationConfig: {
    media_resolution: "medium"
  }
});

const result = await model.generateContent([
  `Analyze this video and provide:
  1. Overall summary
  2. Key scenes and timestamps
  3. Main topics covered`,
  { fileData: { fileUri: file.uri, mimeType: file.mimeType } }
]);

console.log(result.response.text());

動画の仕様：

• 最大時間： 1 時間
• 形式： MP4、MOV、AVI など
• 解像度の選択肢： 低（1 フレームあたり 70 トークン）、中（1 フレームあたり 70 トークン）、高（1 フレームあたり 280 トークン）
• OCR： 高解像度で利用可能

参照： 高度なパターンについては references/video-processing.md を参照してください。

---

タスク 3：音声や発話を処理する

目的： 音声コンテンツを文字起こしして理解し、発話を処理します。

ユースケース：

• 音声の文字起こし
• 発話の分析
• ポッドキャストの要約
• 会議メモ
• 言語の理解
• 音声の分類

Python の例：

import google.generativeai as genai
from pathlib import Path

genai.configure(api_key="YOUR_API_KEY")

model = genai.GenerativeModel("gemini-3-pro-preview")

# Upload audio file (up to 9.5 hours supported)
audio_path = Path("podcast.mp3")
audio_file = genai.upload_file(audio_path)

# Wait for processing
import time
while audio_file.state.name == "PROCESSING":
    time.sleep(5)
    audio_file = genai.get_file(audio_file.name)

# Process audio
response = model.generate_content([
    """Process this audio and provide:
    1. Full transcription
    2. Summary of main points
    3. Key speakers (if multiple)
    4. Important timestamps
    5. Action items or conclusions
    """,
    audio_file
])

print(response.text)
print(f"Tokens used: {response.usage_metadata.total_token_count}")

Node.js の例：

import { GoogleGenerativeAI } from "@google/generative-ai";
import { GoogleAIFileManager, FileState } from "@google/generative-ai/server";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
const fileManager = new GoogleAIFileManager(process.env.GEMINI_API_KEY!);

// Upload audio
const uploadResult = await fileManager.uploadFile("podcast.mp3", {
  mimeType: "audio/mp3"
});

// Wait for processing
let file = await fileManager.getFile(uploadResult.file.name);
while (file.state === FileState.PROCESSING) {
  await new Promise(resolve => setTimeout(resolve, 5000));
  file = await fileManager.getFile(uploadResult.file.name);
}

const model = genAI.getGenerativeModel({ model: "gemini-3-pro-preview" });

const result = await model.generateContent([
  `Process this audio and provide:
  1. Full transcription
  2. Summary of main points
  3. Key timestamps`,
  { fileData: { fileUri: file.uri, mimeType: file.mimeType } }
]);

console.log(result.response.text());

音声の仕様：

• 最大時間： 9.5 時間
• 形式： WAV、MP3、FLAC、AAC など
• 言語： 複数の言語に対応

参照： 高度なパターンについては references/audio-processing.md を参照してください。

タスク 4：PDF ドキュメントを処理する

目標： PDF ドキュメントのコンテンツを抽出し、分析します。

使用例：

• ドキュメント分析
• 情報抽出
• フォーム処理
• 研究論文の分析
• 契約書のレビュー
• 複数ページのドキュメントの理解

Python の例：

import google.generativeai as genai
from pathlib import Path

genai.configure(api_key="YOUR_API_KEY")

# Configure with medium resolution (recommended for PDFs)
model = genai.GenerativeModel(
    "gemini-3-pro-preview",
    generation_config={
        "thinking_level": "high",
        "media_resolution": "medium"  # 560 tokens/page (saturation point)
    }
)

# Upload PDF
pdf_path = Path("research_paper.pdf")
pdf_file = genai.upload_file(pdf_path)

# Wait for processing
import time
while pdf_file.state.name == "PROCESSING":
    time.sleep(5)
    pdf_file = genai.get_file(pdf_file.name)

# Analyze PDF
response = model.generate_content([
    """Analyze this PDF document and provide:
    1. Document type and purpose
    2. Main sections and structure
    3. Key findings or arguments
    4. Important data or statistics
    5. Conclusions or recommendations
    """,
    pdf_file
])

print(response.text)
print(f"Tokens used: {response.usage_metadata.total_token_count}")

Node.js の例：

import { GoogleGenerativeAI } from "@google/generative-ai";
import { GoogleAIFileManager, FileState } from "@google/generative-ai/server";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
const fileManager = new GoogleAIFileManager(process.env.GEMINI_API_KEY!);

// Upload PDF
const uploadResult = await fileManager.uploadFile("research_paper.pdf", {
  mimeType: "application/pdf"
});

// Wait for processing
let file = await fileManager.getFile(uploadResult.file.name);
while (file.state === FileState.PROCESSING) {
  await new Promise(resolve => setTimeout(resolve, 5000));
  file = await fileManager.getFile(uploadResult.file.name);
}

// Analyze with medium resolution (recommended)
const model = genAI.getGenerativeModel({
  model: "gemini-3-pro-preview",
  generationConfig: {
    media_resolution: "medium"
  }
});

const result = await model.generateContent([
  `Analyze this PDF and extract:
  1. Main sections
  2. Key findings
  3. Important data`,
  { fileData: { fileUri: file.uri, mimeType: file.mimeType } }
]);

console.log(result.response.text());

PDF 処理のヒント：

• 推奨解像度： medium（1 ページあたり 560 トークン）— 品質が飽和するポイントです
• 複数ページ： すべてのページを自動的に処理します
• ネイティブサポート： 画像への変換は不要です
• テキスト抽出： 高品質なテキスト抽出機能が組み込まれています

参照： 高度なパターンについては references/document-processing.md をご覧ください

---

タスク 5：メディア処理のコストを最適化する

目標： ユースケースに応じて、品質とトークン消費量のバランスを取ります。

戦略：

メディアタイプ	解像度	トークン数	ユースケース
画像	low	280	素早い確認、サムネイル
画像	medium	560	一般的な分析
画像	high	1,120	OCR、細部、コード
PDF	medium	1 ページあたり 560	推奨（飽和するポイント）
PDF	high	1 ページあたり 1,120	効果が次第に薄れます
動画	low/medium	1 フレームあたり 70	ほとんどのユースケース
動画	high	1 フレームあたり 280	動画からの OCR

Python での最適化例：

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

# Different resolutions for different use cases
def analyze_image_optimized(image_path, need_ocr=False):
    """Analyze image with appropriate resolution"""
    resolution = "high" if need_ocr else "medium"

    model = genai.GenerativeModel(
        "gemini-3-pro-preview",
        generation_config={
            "media_resolution": resolution
        }
    )

    image_file = genai.upload_file(image_path)
    response = model.generate_content([
        "Describe this image" if not need_ocr else "Extract all text from this image",
        image_file
    ])

    # Log token usage for cost tracking
    tokens = response.usage_metadata.total_token_count
    cost = (tokens / 1_000_000) * 2.00  # Input pricing
    print(f"Resolution: {resolution}, Tokens: {tokens}, Cost: ${cost:.6f}")

    return response.text

# Use appropriate resolution
analyze_image_optimized("photo.jpg", need_ocr=False)  # medium
analyze_image_optimized("document.png", need_ocr=True)  # high

項目ごとの解像度制御：

# Set different resolutions for different media in same request
response = model.generate_content([
    "Compare these images",
    {"file": image1, "media_resolution": "high"},  # High detail
    {"file": image2, "media_resolution": "low"},   # Low detail OK
])

コストのモニタリング：

def log_media_costs(response):
    """Log media processing costs"""
    usage = response.usage_metadata

    # Pricing for ≤200k context
    input_cost = (usage.prompt_token_count / 1_000_000) * 2.00
    output_cost = (usage.candidates_token_count / 1_000_000) * 12.00

    print(f"Input tokens: {usage.prompt_token_count} (${input_cost:.6f})")
    print(f"Output tokens: {usage.candidates_token_count} (${output_cost:.6f})")
    print(f"Total cost: ${input_cost + output_cost:.6f}")

参照： 包括的な戦略については references/token-optimization.md をご覧ください

---

メディア解像度の制御

解像度のオプション

設定	画像	PDF	動画（1 フレームあたり）	推奨
low	280 トークン	280 トークン	70 トークン	素早い分析、詳細度低め
medium	560 トークン	560 トークン	70 トークン	品質とコストのバランス
high	1,120 トークン	1,120 トークン	280 トークン	OCR、細かい文字、詳細

設定

グローバル設定（すべてのメディア）：

model = genai.GenerativeModel(
    "gemini-3-pro-preview",
    generation_config={
        "media_resolution": "high"  # Applies to all media
    }
)

項目ごとの設定（解像度の混在）：

response = model.generate_content([
    "Analyze these files",
    {"file": high_detail_image, "media_resolution": "high"},
    {"file": low_detail_image, "media_resolution": "low"}
])

ベストプラクティス

1. 画像： OCR／テキスト抽出には high、一般的な分析には medium を使用します
2. PDF： medium を使用します（品質が飽和するポイントであり、それより高い解像度では効果が次第に薄れます）
3. 動画： OCR が必要な場合を除き、low または medium を使用します
4. コスト管理： low から始め、品質が不十分な場合にのみ解像度を上げます

参照： 詳細なガイドについては references/media-resolution.md をご覧ください

---

ファイル管理

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

import google.generativeai as genai

# Upload file
file = genai.upload_file("path/to/file.jpg")
print(f"Uploaded: {file.name}")

# Check processing status
while file.state.name == "PROCESSING":
    time.sleep(5)
    file = genai.get_file(file.name)

print(f"Status: {file.state.name}")

アップロード済みファイルを一覧表示する

# List all files
for file in genai.list_files():
    print(f"{file.name} - {file.display_name}")

ファイルを削除する

# Delete specific file
genai.delete_file(file.name)

# Delete all files
for file in genai.list_files():
    genai.delete_file(file.name)
    print(f"Deleted: {file.name}")

ファイルのライフサイクル

• アップロード： 即時
• 処理： 非同期（特に動画／音声の場合）
• 保存： ファイルは削除されるまで保持されます
• 有効期限： 一定期間後にファイルの有効期限が切れる場合があります（ドキュメントをご確認ください）

---

複数ファイルの処理

複数の画像を処理する

# Upload multiple images
images = [
    genai.upload_file("photo1.jpg"),
    genai.upload_file("photo2.jpg"),
    genai.upload_file("photo3.jpg")
]

# Analyze together
response = model.generate_content([
    "Compare these images and identify common elements",
    *images
])

print(response.text)

複数のメディアタイプを組み合わせる

# Combine different media types
image = genai.upload_file("chart.png")
pdf = genai.upload_file("report.pdf")

response = model.generate_content([
    "Does the chart match the data in the report?",
    image,
    pdf
])

---

参考資料

基本ガイド

• 画像の理解 - 画像分析の包括的なパターン
• 動画処理 - 動画分析とフレーム抽出
• 音声処理 - 音声の文字起こしと分析
• ドキュメント処理 - PDF とドキュメントからの抽出

最適化

• メディア解像度 - 解像度の制御と品質の調整
• OCR 抽出 - テキスト抽出のベストプラクティス
• トークンの最適化 - コスト管理と効率化

スクリプト

• 画像分析スクリプト - 本番環境向けの画像分析
• 動画処理スクリプト - 動画処理の自動化
• 音声処理スクリプト - 音声の文字起こし
• PDF 処理スクリプト - PDF からの抽出

公式リソース

• ビジョン機能
• メディアを使ったプロンプト
• ファイル API

---

関連スキル

• gemini-3-pro-api - 基本設定、認証、テキスト生成
• gemini-3-image-generation - 画像の出力（画像の生成）
• gemini-3-advanced - 関数呼び出し、ツール、キャッシュ、バッチ処理

---

一般的なユースケース

ビジュアル Q&A アプリケーション

画像の理解機能とチャットを組み合わせます。

model = genai.GenerativeModel("gemini-3-pro-preview")
chat = model.start_chat()

# Upload image
image = genai.upload_file("product.jpg")

# Ask questions about it
response1 = chat.send_message(["What product is this?", image])
response2 = chat.send_message("What are its main features?")
response3 = chat.send_message("What's the price range for similar products?")

ドキュメント分析パイプライン

複数の PDF を処理して、洞察を抽出します。

import google.generativeai as genai
from pathlib import Path

genai.configure(api_key="YOUR_API_KEY")

model = genai.GenerativeModel(
    "gemini-3-pro-preview",
    generation_config={"media_resolution": "medium"}
)

# Process all PDFs in directory
pdf_dir = Path("documents/")
results = {}

for pdf_path in pdf_dir.glob("*.pdf"):
    pdf_file = genai.upload_file(pdf_path)

    # Wait for processing
    while pdf_file.state.name == "PROCESSING":
        time.sleep(5)
        pdf_file = genai.get_file(pdf_file.name)

    # Extract key information
    response = model.generate_content([
        "Extract: 1) Document type, 2) Key dates, 3) Important numbers, 4) Summary",
        pdf_file
    ])

    results[pdf_path.name] = response.text

    # Clean up
    genai.delete_file(pdf_file.name)

# Save results
import json
with open("analysis_results.json", "w") as f:
    json.dump(results, f, indent=2)

動画コンテンツのモデレーション

動画を分析して、特定のコンテンツを検出します。

video = genai.upload_file("user_upload.mp4")

# Wait for processing
while video.state.name == "PROCESSING":
    time.sleep(10)
    video = genai.get_file(video.name)

response = model.generate_content([
    """Analyze this video for:
    1. Inappropriate content (yes/no)
    2. Violence or harmful content (yes/no)
    3. Overall content rating (G/PG/PG-13/R)
    4. Brief justification

    Provide structured response.
    """,
    video
])

print(response.text)

---

トラブルシューティング

問題：ファイル処理が「PROCESSING」のまま進まない

解決策： 大きなファイル（特に動画）は処理に時間がかかることがあります。確認の間隔を 30～60 秒空けてください。5 分以上進まない場合、ファイルの処理に失敗している可能性があります。

問題：OCR の結果の精度が低い

解決策： テキストを含む画像には media_resolution: "high" を使用してください。画像が鮮明で、高解像度であることを確認してください。

問題：トークンコストが高い

解決策： 適切なメディア解像度を使用してください。まずは low から始め、必要な場合にのみ上げてください。PDF には通常 medium で十分です。

問題：動画分析で詳細が見落とされる

解決策： フレーム分析の精度を高めるには media_resolution: "high" を使用するか、確認したい内容をより具体的にプロンプトで指定してください。

問題：音声の文字起こしが不正確

解決策： 音声の品質が良好であること（過剰な背景ノイズがないこと）を確認してください。アクセント、言語、専門分野についての情報をプロンプトに含めてください。

---

まとめ

このスキルは、マルチモーダル入力を処理するための包括的な機能を提供します。

✅ OCR と物体検出を使った画像分析
✅ 最大 1 時間の動画処理
✅ 最大 9.5 時間の音声の文字起こし
✅ PDF ドキュメントのネイティブ処理
✅ メディア解像度のきめ細かな制御
✅ トークン最適化の戦略
✅ 複数ファイルの処理
✅ 本番環境向けのサンプル

マルチモーダルコンテンツを分析する準備はできましたか？ 上記から、ユースケースに合ったタスクを始めてください！