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 等
• 分辨率选项： 低（70 个令牌／帧）、中（70 个令牌／帧）、高（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（每页 560 个 token）——质量饱和点
• 多页： 自动处理所有页面
• 原生支持： 无需转换为图像
• 文本提取： 内置高质量文本提取功能

参见： references/document-processing.md，了解高级模式

---

任务 5：优化媒体处理成本

目标： 根据用例平衡质量和 token 消耗。

策略：

媒体类型	分辨率	Token 数	用例
图像	low	280	快速扫描、缩略图
图像	medium	560	常规分析
图像	high	1,120	OCR、精细细节、代码
PDF	medium	560/页	推荐（饱和点）
PDF	high	1,120/页	收益递减
视频	low/medium	70/帧	大多数用例
视频	high	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	视频（每帧）	建议
low	280 个 token	280 个 token	70 个 token	快速分析，细节较少
medium	560 个 token	560 个 token	70 个 token	平衡质量与成本
high	1,120 个 token	1,120 个 token	280 个 token	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 - 函数调用、工具、缓存、批处理

---

常见用例

视觉问答应用

将图像理解与聊天结合：

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 文档处理 ✅ 精细的媒体分辨率控制 ✅ 令牌优化策略 ✅ 多文件处理 ✅ 可用于生产环境的示例

准备好分析多模态内容了吗？ 从上方选择与你的用例匹配的任务开始！