手把手教你使用 Gemini 3 Flash API，涵盖环境配置、基础调用、高级特性、成本优化和生产最佳实践。

一、准备工作

1.1 获取 API Key

你有以下几种方式获取 API 访问权限：

方式一：Google AI Studio（推荐新手和原型开发）

1. 访问 aistudio.google.com
2. 使用 Google 账号登录
3. 在模型选择中找到 Gemini 3 Flash Preview
4. 点击 “Get API Key” 生成密钥
5. 安全存储密钥（后面会讲最佳实践）

优点：

• 即时获取，无需信用卡
• 界面友好，适合快速验证想法
• 有免费额度

方式二：Vertex AI（推荐生产环境）

1. 创建 Google Cloud 项目
2. 启用 Vertex AI API
3. 创建服务账号并配置 IAM 权限
4. 使用 Application Default Credentials (ADC) 认证

优点：

• 企业级权限管理
• 配额和计费控制
• 区域数据驻留
• 完整的日志和监控

方式三：使用中转服务

如果你不想去折腾各种各样的环境（dddd），或者在不同场景下可能有使用不同llm的需求，可以使用中转服务，一个key走天下，我自己用得比较多的是 147API （https://147ai.com/）这个平台，使用上也很简单，大家感兴趣的话后面我出一期详细的使用教程

1.2 环境变量配置

绝对不要把 API Key 硬编码在代码里！

# macOS/Linux
export GEMINI_API_KEY="your-api-key-here"

# Windows PowerShell
$env:GEMINI_API_KEY="your-api-key-here"

# 或者使用 .env 文件（配合 dotenv 库）
echo "GEMINI_API_KEY=your-api-key-here" > .env

1.3 模型信息速查

参数	值
模型名称	gemini-3-flash-preview
API端点	https://generativelanguage.googleapis.com/v1beta/
上下文窗口	1,000,000 tokens
最大输出	~65,535 tokens

二、基础调用

2.1 REST API 调用示例

最直接的方式是使用 cURL：

curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "用一句话解释什么是机器学习"}]
      }
    ]
  }'

2.2 Python SDK 调用

首先安装 SDK：

pip install google-generativeai

基础调用：

import google.generativeai as genai
import os

# 配置 API Key
genai.configure(api_key=os.environ["GEMINI_API_KEY"])

# 创建模型实例
model = genai.GenerativeModel("gemini-3-flash-preview")

# 简单调用
response = model.generate_content("用一句话解释什么是机器学习")
print(response.text)

2.3 流式响应

对于需要实时显示的场景：

# 流式输出
response = model.generate_content(
    "写一首关于AI的诗",
    stream=True
)

for chunk in response:
    print(chunk.text, end="", flush=True)

2.4 多轮对话

# 创建对话
chat = model.start_chat(history=[])

# 第一轮
response1 = chat.send_message("我想学习Python")
print(response1.text)

# 第二轮（模型记得上下文）
response2 = chat.send_message("有什么入门资源推荐吗？")
print(response2.text)

三、多模态调用

3.1 图像理解

import PIL.Image

# 加载图像
image = PIL.Image.open("example.jpg")

# 图像+文本提问
response = model.generate_content([
    "这张图片里有什么？请详细描述。",
    image
])
print(response.text)

3.2 PDF 文档处理

# 上传 PDF
pdf_file = genai.upload_file("document.pdf")

# 提问
response = model.generate_content([
    "总结这份文档的主要内容",
    pdf_file
])
print(response.text)

3.3 视频分析

# 上传视频
video_file = genai.upload_file("video.mp4")

# 等待处理完成
import time
while video_file.state.name == "PROCESSING":
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

# 分析视频
response = model.generate_content([
    "描述这个视频的主要内容，并列出关键时间点",
    video_file
])
print(response.text)

3.4 音频处理

# 上传音频（支持最长约8.4小时）
audio_file = genai.upload_file("audio.mp3")

# 转录或分析
response = model.generate_content([
    "请转录这段音频，并总结主要内容",
    audio_file
])
print(response.text)

四、高级参数调优

4.1 Thinking Level（推理深度）

这是 Gemini 3 Flash 的核心新特性：

from google.generativeai import GenerationConfig

# 配置推理深度
config = GenerationConfig(
    thinking_level="high"  # minimal, low, medium, high
)

response = model.generate_content(
    "证明根号2是无理数",
    generation_config=config
)

选择指南：

等级	适用场景	延迟	成本
minimal	简单问答、快速响应	最低	最低
low	日常对话	低	低
medium	一般分析	中	中
high	复杂推理、数学证明	高	高

4.2 Media Resolution（视觉精度）

控制图像/视频的处理精度：

config = GenerationConfig(
    media_resolution="high"  # low, medium, high, ultra-high
)

response = model.generate_content(
    ["识别图片中的所有文字", image],
    generation_config=config
)

选择指南：

精度	适用场景	Token消耗
low	快速预览	最少
medium	一般识别	中等
high	文字识别	较多
ultra-high	精密分析	最多

4.3 Temperature 和其他参数

config = GenerationConfig(
    temperature=1.0,  # 建议保持默认1.0
    top_p=0.95,
    top_k=40,
    max_output_tokens=8192,
    stop_sequences=["END"]
)

⚠️ 重要提示：官方建议保持 temperature=1.0，偏离默认值可能影响推理性能。

4.4 结构化输出

强制模型输出 JSON：

import json

response = model.generate_content(
    """
    分析以下文本的情感，返回JSON格式：
    {"sentiment": "positive/negative/neutral", "confidence": 0-1, "keywords": []}
    
    文本：今天天气真好，心情很愉快！
    """,
    generation_config=GenerationConfig(
        response_mime_type="application/json"
    )
)

result = json.loads(response.text)
print(result)

五、Function Calling（函数调用）

5.1 定义函数

# 定义工具函数
def get_weather(location: str, unit: str = "celsius"):
    """获取指定地点的天气信息"""
    # 这里是实际的API调用（示例返回）
    return {"location": location, "temperature": 22, "unit": unit}

# 创建工具配置
tools = [
    genai.protos.Tool(
        function_declarations=[
            genai.protos.FunctionDeclaration(
                name="get_weather",
                description="获取指定地点的天气信息",
                parameters=genai.protos.Schema(
                    type=genai.protos.Type.OBJECT,
                    properties={
                        "location": genai.protos.Schema(type=genai.protos.Type.STRING),
                        "unit": genai.protos.Schema(type=genai.protos.Type.STRING)
                    },
                    required=["location"]
                )
            )
        ]
    )
]

5.2 使用函数调用

# 创建支持函数调用的模型
model = genai.GenerativeModel("gemini-3-flash-preview", tools=tools)

# 发起请求
response = model.generate_content("北京今天天气怎么样？")

# 检查是否需要调用函数
for part in response.candidates[0].content.parts:
    if hasattr(part, 'function_call'):
        fc = part.function_call
        # 执行函数
        result = get_weather(fc.args["location"])
        # 返回结果给模型继续生成

5.3 流式函数调用（新特性）

Gemini 3 Flash 支持在函数调用过程中流式返回参数：

response = model.generate_content(
    "帮我查询北京和上海的天气",
    stream=True
)

for chunk in response:
    # 可以更早地获取部分参数
    process_chunk(chunk)

六、Thought Signatures 处理

6.1 什么是 Thought Signatures？

Thought Signatures 是模型推理过程的加密表示，用于在多轮对话中保持推理连贯性。

6.2 正确处理方式

# 第一轮对话
response1 = chat.send_message("解释量子纠缠")

# response1 中会包含 thought_signature
# 在后续请求中需要原样传回（SDK通常自动处理）

# 第二轮对话（模型保持推理连贯性）
response2 = chat.send_message("它有什么实际应用？")

⚠️ 关键规则：

1. 必须原样传回收到的 Thought Signatures
2. 即使 thinking_level 为 minimal 也需要传递
3. 使用官方 SDK 通常会自动处理

七、成本优化技巧

7.1 使用 Context Caching

对于需要重复使用相同上下文的场景：

# 缓存大型上下文
cached_content = genai.caching.CachedContent.create(
    model="gemini-3-flash-preview",
    contents=large_document  # 大型文档
)

# 后续请求使用缓存
model = genai.GenerativeModel.from_cached_content(cached_content)
response = model.generate_content("基于文档回答：...")

节省比例：最高可达 90% 的token成本！

7.2 优化 Token 使用

# 1. 使用简洁的提示词
# ❌ 不好
prompt = "你好，我想请你帮我做一件事情，就是能不能请你帮我总结一下这篇文章的主要内容呢？非常感谢！"

# ✅ 更好
prompt = "总结以下文章的主要内容："

# 2. 限制输出长度
config = GenerationConfig(max_output_tokens=500)

# 3. 合理使用 thinking_level
# 简单任务用 minimal，复杂任务才用 high

7.3 批量处理

对于大量请求，使用 Batch API：

# 批量请求可以获得更低的价格
# 具体实现参考官方 Batch API 文档

7.4 监控和预算

# 记录每次请求的 token 使用
response = model.generate_content(prompt)
print(f"输入: {response.usage_metadata.prompt_token_count}")
print(f"输出: {response.usage_metadata.candidates_token_count}")

# 计算成本
input_cost = response.usage_metadata.prompt_token_count / 1_000_000 * 0.50
output_cost = response.usage_metadata.candidates_token_count / 1_000_000 * 3.00
total_cost = input_cost + output_cost

八、生产环境最佳实践

8.1 错误处理

import google.api_core.exceptions
import time

def call_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = model.generate_content(prompt)
            return response
        except google.api_core.exceptions.ResourceExhausted:
            # 速率限制，等待后重试
            wait_time = 2 ** attempt  # 指数退避
            time.sleep(wait_time)
        except google.api_core.exceptions.ServiceUnavailable:
            # 服务暂时不可用
            time.sleep(5)
        except Exception as e:
            print(f"未知错误: {e}")
            raise
    
    raise Exception("超过最大重试次数")

8.2 超时设置

import google.generativeai as genai

# 设置请求超时
genai.configure(
    api_key=os.environ["GEMINI_API_KEY"],
    transport="rest",  # 或 "grpc"
)

# 对于长任务，适当延长超时

8.3 日志记录

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def logged_generate(prompt):
    logger.info(f"请求开始: {prompt[:100]}...")
    start_time = time.time()
    
    response = model.generate_content(prompt)
    
    elapsed = time.time() - start_time
    logger.info(f"请求完成: {elapsed:.2f}秒, tokens: {response.usage_metadata.total_token_count}")
    
    return response

8.4 安全考虑

# 1. 使用环境变量存储密钥
api_key = os.environ.get("GEMINI_API_KEY")
if not api_key:
    raise ValueError("GEMINI_API_KEY 未设置")

# 2. 验证用户输入
def sanitize_input(user_input):
    # 防止注入攻击
    # 限制长度
    # 过滤敏感内容
    return cleaned_input

# 3. 过滤模型输出
def filter_response(response):
    # 检查是否包含不当内容
    # 验证输出格式
    return filtered_response

8.5 使用 Vertex AI（企业级）

import vertexai
from vertexai.generative_models import GenerativeModel

# 初始化
vertexai.init(project="your-project-id", location="us-central1")

# 创建模型
model = GenerativeModel("gemini-3-flash-preview")

# 调用（与 Google AI SDK 类似）
response = model.generate_content(prompt)

Vertex AI 的优势：

• IAM 权限管理
• VPC 服务控制
• 审计日志
• SLA 保障

九、常见问题排查

9.1 认证错误

Error: API key not valid

解决方案：

1. 检查 API Key 是否正确
2. 确认环境变量是否设置
3. 检查是否启用了正确的 API

9.2 速率限制

Error: 429 Resource Exhausted

解决方案：

1. 实现指数退避重试
2. 检查账户配额
3. 考虑升级到付费计划

9.3 上下文过长

Error: Request payload size exceeds the limit

解决方案：

1. 压缩输入内容
2. 使用摘要替代全文
3. 分批处理

9.4 预览版本注意事项

Gemini 3 Flash 目前是 Preview 版本：

• API 可能有 breaking changes
• 关注官方更新公告
• 保持 SDK 版本更新

十、下一步

10.1 官方资源

• Google AI Studio - 在线测试
• Gemini API 文档 - 完整文档
• Vertex AI 文档 - 企业级部署

10.2 示例项目

可以尝试构建：

1. 多模态聊天机器人
2. 文档分析工具
3. 视频内容摘要器
4. 代码生成助手

10.3 社区资源

• Google AI Discord
• Stack Overflow - google-cloud-vertex-ai