Google Gemini API 完全指南

【AI&游戏】专栏-直达

Google Gemini API是Google DeepMind团队打造的大语言模型服务，提供了业界领先的多模态AI能力。作为Google在AI领域的重要战略产品，Gemini系列模型在2023年12月正式发布后迅速成为业界焦点。与其他模型相比，Gemini在长上下文窗口、多模态理解、视频处理和成本效率等方面展现出独特的优势。本篇文章将全面介绍Google Gemini API的核心功能、模型家族、开发指南以及在游戏开发中的应用场景。

一、Google AI与Gemini概述

1.1 Gemini的诞生与发展

Google在人工智能领域拥有深厚的技术积累，从早期的AlphaGo到Transformer架构的发明，Google的研究团队持续推动着AI技术的发展。2023年12月，Google正式发布Gemini 1.0，这是其首个原生多模态大语言模型，能够同时理解和处理文本、图像、音频、视频等多种形式的信息。

Gemini的名称来源于拉丁语"gemellus"，意为"双胞胎"，象征着模型的多模态本质和对复杂任务的处理能力。从发布之初，Gemini就被设计为Google AI产品的核心技术支撑，应用于从Bard聊天机器人到Pixel设备的各项服务中。

2024年2月，Google发布了Gemini 1.5系列，引入了突破性的百万token上下文窗口，在长文档理解、视频分析和多模态推理方面实现了质的飞跃。2024年5月的Google I/O大会上，Gemini 1.5 Pro正式向开发者开放API，同时推出了更轻量的Gemini 1.5 Flash版本。

2025年，Gemini 2.0和2.5系列相继发布，带来了更强的推理能力、更长的上下文和更丰富的功能。2026年，Gemini 3系列正式登场，包括Gemini 3 Pro、Gemini 3 Flash和Gemini 3.1 Flash-Lite，继续巩固Google在AI领域的领先地位。

1.2 Gemini的核心优势

Gemini在多个技术维度上展现出显著优势：

超长上下文窗口：Gemini 1.5 Pro最初提供100万token的上下文窗口，后续版本进一步扩展。这一能力使得处理整本书籍、完整代码库或数小时视频成为可能。

原生多模态：不同于其他先训练文本模型再添加视觉能力的方案，Gemini从一开始就是多模态训练的，能够更深入地理解和关联不同模态的信息。

高效的推理：Gemini Flash系列针对速度和成本进行了优化，能够在保持良好性能的同时提供极快的响应速度和极低的API成本。

Google生态整合：Gemini与Google Cloud、Google AI Studio、Google Workspace等产品和平台深度整合，为企业用户提供了完整的AI解决方案。

视频理解能力：Gemini 2.5能够处理长达数小时的视频内容，提取关键信息、分析场景变化、理解视频中的动作和对话。

二、Gemini模型家族详解

2.1 Gemini 3系列（最新一代）

2026年发布的Gemini 3系列代表了Google最新的AI技术成果。

Gemini 3.1 Pro 是面向复杂任务的旗舰模型，具备高级智能和强大的问题解决能力。它在编码、推理和创意任务上表现优异，特别适合需要深度分析的专业应用场景。

Gemini 3 Flash 是平衡性能和成本的理想选择，在保持接近大型模型能力的同时，大幅降低了计算成本和响应延迟。

Gemini 3.1 Flash-Lite 是最经济的选项，适合大规模部署和对成本敏感的应用场景。

Gemini 3 Nano 系列（包括Nano Banana 2和Nano Banana Pro）是专门针对图像生成和编辑优化的模型，提供高速、高质量的图像创作能力。

2.2 Gemini 2.5系列

Gemini 2.5系列是2025年的主力产品，引入了多项重要功能升级。

Gemini 2.5 Pro 是该系列的旗舰模型，在编程、推理和多模态理解方面达到了新的高度。作为思考模型（Thinking Model），它能够进行复杂的推理和规划，适合构建AI代理和工作流自动化系统。

Gemini 2.5 Flash 是面向快速响应的优化版本，以极低的成本提供优秀的性能。它特别适合需要处理大量请求的实时应用。

Gemini 2.5 Flash-Lite 是最轻量的选项，适合简单查询和大批量处理场景。

Gemini 2.5的关键特性包括：

• 深度思考模式：模型可以在生成响应前进行多步推理
• 视频理解：能够处理长达3小时的视频内容
• 代理能力增强：更好的工具使用和函数调用能力
• 上下文缓存：支持长上下文的缓存以优化成本

2.3 Gemini 2.0系列

Gemini 2.0 Flash是2.0系列的代表产品，为开发者提供了稳定可靠的API服务。虽然已被2.5和3系列超越，但2.0 Flash在某些场景下仍然是合适的选择。

2.4 模型选择指南

模型	适用场景	上下文窗口	特点
Gemini 3.1 Pro	复杂推理、深度分析	100万+ tokens	最强能力，最高成本
Gemini 3 Flash	平衡应用、通用任务	较长	性能成本平衡
Gemini 3.1 Flash-Lite	简单任务、大批量	中等	最经济
Gemini 2.5 Pro	专业编码、代理任务	100万 tokens	思考能力强
Gemini 2.5 Flash	快速响应、实时应用	较长	速度快
Gemini 2.0 Flash	稳定生产	100万 tokens	成熟稳定

三、Gemini API核心功能

3.1 基础文本生成

Gemini API的基本使用非常简单：

import google.generativeai as genai

genai.configure(api_key="your-api-key")

model = genai.GenerativeModel("gemini-3.1-pro")

response = model.generate_content("解释什么是大语言模型")

print(response.text)

API设计简洁直观，与OpenAI的SDK风格相似，便于开发者迁移和上手。

3.2 多轮对话

Gemini支持多轮对话上下文：

chat = model.start_chat(history=[
    {
        "role": "user",
        "parts": ["你好，我是一个游戏开发者。"]
    },
    {
        "role": "model",
        "parts": ["你好！很高兴认识你。作为游戏开发者，我可以帮助你设计游戏AI、生成剧情内容或者解答技术问题。有什么我可以帮你的吗？"]
    }
])

response = chat.send_message("我想设计一个智能NPC系统，有什么建议吗？")
print(response.text)

3.3 多模态输入

Gemini的原生多模态能力使其能够处理多种形式的输入：

from PIL import Image

# 图片输入
image = Image.open("game_concept.png")

response = model.generate_content([
    image,
    "请分析这张游戏概念设计图，描述其中的主要元素和设计风格。"
])

print(response.text)

# 视频输入
import google.generativeai as genai

video_file = genai.upload_file("gameplay_video.mp4")

response = model.generate_content([
    video_file,
    "分析这段游戏玩法视频，指出游戏的核心机制和用户体验特点。"
])

print(response.text)

Gemini 2.5能够处理长达数小时的视频，提取关键帧、分析场景变化、理解语音对话和视觉元素。

3.4 系统指令

Gemini支持通过system instruction设定模型行为：

model = genai.GenerativeModel(
    "gemini-3.1-pro",
    system_instruction="你是一个专业的游戏关卡设计师，拥有10年以上的从业经验。你的建议应该结合创意性和可实现性，同时考虑玩家的游戏体验。"
)

response = model.generate_content(
    "为一个RPG游戏设计一个地下城关卡，要求有3个BOSS和2个隐藏房间。"
)

print(response.text)

3.5 生成配置

Gemini提供丰富的生成配置选项：

from google.generativeai.types import HarmCategory, HarmBlockThreshold

response = model.generate_content(
    "生成一个游戏故事开头",
    generation_config=genai.types.GenerationConfig(
        candidate_count=1,
        max_output_tokens=2048,
        temperature=0.7,
        top_p=0.9,
        top_k=40
    ),
    safety_settings={
        HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
        HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
        HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
        HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
    }
)

主要参数说明：

• candidate_count：生成的候选回复数量
• max_output_tokens：最大输出token数
• temperature：控制输出的随机性，0表示确定性输出，1表示最大随机性
• top_p和top_k：核采样参数，控制token选择的概率分布

3.6 函数调用（Function Calling）

Gemini支持Function Calling，可以与外部系统集成：

def get_character_stats(character_id: str) -> dict:
    """获取角色属性"""
    return {"hp": 100, "mp": 50, "level": 10}

def get_item_info(item_name: str) -> dict:
    """获取物品信息"""
    return {"name": item_name, "type": "weapon", "rarity": "rare"}

tools = [
    {
        "function_declarations": [
            {
                "name": "get_character_stats",
                "description": "获取角色的当前属性状态",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "character_id": {"type": "string", "description": "角色唯一标识符"}
                    },
                    "required": ["character_id"]
                }
            },
            {
                "name": "get_item_info",
                "description": "获取物品的详细信息",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "item_name": {"type": "string", "description": "物品名称"}
                    },
                    "required": ["item_name"]
                }
            }
        ]
    }
]

model = genai.GenerativeModel(
    "gemini-3.1-pro",
    tools=tools
)

response = model.generate_content(
    "我的角色hero_001当前有多少生命值？我有一把叫做'火焰之剑'的武器，它是什么类型的装备？"
)

# 处理函数调用
for part in response.parts:
    if part.function_call:
        if part.function_call.name == "get_character_stats":
            result = get_character_stats(**part.function_call.args)
        elif part.function_call.name == "get_item_info":
            result = get_item_info(**part.function_call.args)
        
        # 将结果返回给模型
        response = model.generate_content([
            response,
            {
                "role": "user",
                "parts": [{
                    "function_response": {
                        "name": part.function_call.name,
                        "response": result
                    }
                }]
            }
        ])

3.7 上下文缓存（Context Caching）

对于需要处理长上下文的场景，上下文缓存可以显著降低成本：

# 上传长文档
long_document = genai.upload_file("game_design_document.pdf")

# 创建缓存
cache = genai.create_cached_content(
    model="gemini-3.1-pro",
    contents=long_document,
    system_instruction="你是游戏设计专家，分析给定的设计文档。",
    ttl="1h"
)

cached_model = genai.GenerativeModel.from_cached_content(cached_content=cache)

# 使用缓存进行多次查询
response1 = cached_model.generate_content("文档中的核心游戏机制是什么？")
response2 = cached_model.generate_content("角色成长系统是如何设计的？")

上下文缓存特别适合需要反复查询同一份长文档的场景，如代码库分析、长篇文章阅读理解等。

3.8 Embeddings与向量搜索

Gemini还提供文本嵌入功能：

result = genai.embed_content(
    model="gemini-embedding-exp",
    content="这是要嵌入的文本内容",
    task_type="RETRIEVAL_DOCUMENT",
    title="游戏AI设计"
)

embedding = result.embedding
print(f"嵌入向量维度: {len(embedding)}")

嵌入向量可用于语义搜索、相似度匹配、文档聚类等应用。

四、Google AI Studio与开发工具

4.1 Google AI Studio

Google AI Studio是基于浏览器的Gemini开发环境，提供：

• 交互式API测试
• Prompt设计和迭代
• API密钥管理
• 代码生成和导出
• 模型性能监控

访问 https://aistudio.google.com 开始使用。

4.2 Python SDK安装与配置

pip install google-generativeai

import google.generativeai as genai

# 配置API密钥
genai.configure(api_key="YOUR_API_KEY")

# 列出可用模型
for m in genai.list_models():
    if "generateContent" in m.supported_generation_methods:
        print(m.name)

4.3 Vertex AI集成

对于企业用户，Gemini也可以通过Google Cloud的Vertex AI平台访问：

from vertexai.generative_models import GenerativeModel

model = GenerativeModel("gemini-3.1-pro")

response = model.generate_content("Hello, Gemini!")
print(response.text)

Vertex AI提供了更丰富的企业级功能，包括数据治理、安全控制、SLA保障等。

五、定价与成本管理

5.1 定价结构

Gemini API采用按token计费的模式，不同模型的定价差异较大：

模型	输入价格	输出价格	特点
Gemini 3.1 Pro	中等	中等	最强能力
Gemini 3 Flash	较低	较低	性能平衡
Gemini 3.1 Flash-Lite	极低	极低	最经济
Gemini 2.5 Pro	中等	中等	思考能力强

5.2 免费额度

Google为Gemini API提供了慷慨的免费额度：

• Gemini 3 Flash：每月大量免费token
• Gemini 3.1 Flash-Lite：更多免费token
• Gemini 2.0 Flash：持续免费使用

具体免费额度请参考官方定价页面。

5.3 成本优化策略

模型选择：简单任务使用Flash系列，复杂任务才使用Pro版本。

缓存利用：对于重复查询同一内容的情况，使用上下文缓存。

Prompt优化：精简Prompt内容，减少不必要的token消耗。

批量处理：非实时任务收集后批量处理。

六、在游戏开发中的应用

6.1 游戏叙事生成

Gemini的超长上下文和视频理解能力使其在游戏内容生成方面有独特优势：

def generate_game_story(game_theme, player_choices):
    """
    基于玩家选择生成游戏剧情
    """
    model = genai.GenerativeModel("gemini-3.1-pro")
    
    prompt = f"""作为一个专业游戏叙事设计师，基于以下信息创作一个引人入胜的游戏故事：

    游戏主题：{game_theme}
    玩家选择：{player_choices}
    
    请生成包含以下内容的完整叙事：
    1. 故事背景设定
    2. 主要角色介绍（至少3个）
    3. 开场场景描述
    4. 3个分支选项及其可能的后果
    5. 伏笔和悬念设计
    
    叙事风格要符合主题要求，文字要有画面感。"""
    
    response = model.generate_content(prompt)
    return response.text

6.2 游戏资产分析

利用Gemini的多模态能力分析游戏资产：

def analyze_game_asset(asset_file, asset_type):
    """
    分析游戏资产并提供改进建议
    """
    model = genai.GenerativeModel("gemini-3.1-pro")
    
    if asset_type == "image":
        asset = Image.open(asset_file)
        prompt = "请分析这张游戏UI设计图，提供设计改进建议。"
    elif asset_type == "video":
        asset = genai.upload_file(asset_file)
        prompt = "分析这段游戏宣传视频的制作质量和市场吸引力。"
    elif asset_type == "audio":
        prompt = "分析这段游戏BGM的特点和适用场景。"
    
    response = model.generate_content([asset, prompt])
    return response.text

6.3 智能游戏助手

构建能够理解游戏上下文并提供帮助的AI助手：

game_assistant_tools = [
    {
        "function_declarations": [{
            "name": "search_game_manual",
            "description": "搜索游戏手册中的相关信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"}
                }
            }
        }, {
            "name": "get_achievement_guide",
            "description": "获取成就达成指南",
            "parameters": {
                "type": "object",
                "properties": {
                    "achievement_id": {"type": "string"}
                }
            }
        }]
    }
]

model = genai.GenerativeModel(
    "gemini-3.1-pro",
    tools=game_assistant_tools,
    system_instruction="你是一个友好的游戏助手，能够回答玩家关于游戏机制、攻略、技巧等问题。"
)

def player_help(message):
    response = model.generate_content(message)
    return response.text

6.4 游戏测试辅助

def generate_test_cases(game_features):
    """
    根据游戏功能生成测试用例
    """
    model = genai.GenerativeModel("gemini-3.1-pro")
    
    prompt = f"""作为游戏测试专家，为以下游戏功能设计全面的测试用例：

    游戏功能：{game_features}
    
    请提供：
    1. 功能测试用例（正常流程）
    2. 边界条件测试
    3. 异常情况处理测试
    4. 性能压力测试场景
    5. 兼容性测试要求
    
    每个测试用例应包含：测试目标、输入条件、预期结果。"""
    
    response = model.generate_content(prompt)
    return response.text

七、最佳实践

7.1 Prompt工程技巧

• 使用明确的指令和角色设定
• 对于复杂任务，使用分步骤的Prompt
• 利用Few-shot示例帮助模型理解期望格式
• 注意Prompt长度和成本的平衡

7.2 错误处理与重试

from google.api_core.exceptions import GoogleAPICallError, RateLimitExceeded

def call_gemini_with_retry(prompt, max_retries=3):
    for i in range(max_retries):
        try:
            response = model.generate_content(prompt)
            return response
        except RateLimitExceeded:
            if i < max_retries - 1:
                time.sleep(2 ** i)
            else:
                raise
        except GoogleAPICallError as e:
            raise

7.3 安全考虑

Gemini内置了多层安全过滤机制，包括：

• 有害内容检测
• 敏感信息过滤
• 偏见检测和缓解

对于有特殊安全要求的应用，可以调整safety_settings参数。

八、常见问题

8.1 API访问问题

国内开发者可能需要使用代理服务访问Google AI API。建议使用稳定可靠的网络环境。

8.2 模型选择困惑

选择模型时考虑以下因素：

• 任务复杂度：简单任务用Flash，复杂任务用Pro
• 延迟要求：实时应用选择Flash
• 成本预算：预算有限优先Flash
• 上下文长度：超长上下文选择Pro

8.3 输出质量不稳定

可以尝试：

• 降低temperature以获得更稳定的输出
• 使用更详细的system instruction
• 添加输出格式示例
• 调整top_p和top_k参数

---

总结

Google Gemini API凭借其超长上下文、原生多模态能力和Google生态的深度整合，成为AI开发者的重要选择。从Gemini 1.5到最新的Gemini 3系列，Google持续推动着AI技术的发展。对于游戏开发者而言，Gemini的多模态能力和超长上下文特别适合构建智能游戏助手、内容生成系统和复杂的NPC交互系统。掌握Gemini API的使用，将为您的游戏开发工作带来强大助力。

---

（欢迎点赞留言探讨，更多人加入进来能更加完善这个探索的过程，🙏）