快速开始指南

5分钟上手

🎯 最快体验方式

想要立即开始使用 Gemini 3.0？

无需注册 API，无需科学上网，直接访问以下中文镜像站点：

🚀 XSimpleChat - https://xsimplechat.com - 简洁易用，即开即用
🚀 蓝鲸Chat - https://lanjingchat.com - 专业稳定，功能完整

适合快速体验和日常使用！下面的 API 指南适合需要集成到自己应用的开发者。

本指南将帮助你在 5 分钟内开始使用 Gemini 3.0 API。

📋 前置要求

在开始之前，请确保你有：

✅ Google 账号
✅ 基础的编程知识（Python、JavaScript 或其他语言）
✅ 终端或命令行工具
✅ 网络连接

🔑 步骤 1：获取 API 密钥

方法一：Google AI Studio（推荐新手）

访问 Google AI Studio
使用 Google 账号登录
点击 "Get API Key" 或 "获取 API 密钥"
创建新项目或选择现有项目
复制生成的 API 密钥

免费额度

Google AI Studio 提供免费的 API 调用配额，适合开发和测试使用

方法二：Google Cloud Console（企业用户）

访问 Google Cloud Console
创建新项目或选择现有项目
启用 "Generative Language API"
创建凭据（API 密钥）
设置配额和计费

安全提示

请妥善保管 API 密钥，不要在公共代码仓库中暴露

🚀 步骤 2：安装 SDK

根据你使用的编程语言选择相应的 SDK：

Python

bash

# 使用 pip 安装
pip install google-generativeai

# 或使用特定版本
pip install google-generativeai==0.3.0

Node.js / JavaScript

bash

# 使用 npm 安装
npm install @google/generative-ai

# 使用 yarn 安装
yarn add @google/generative-ai

Go

bash

go get github.com/google/generative-ai-go

其他语言

使用 REST API 直接调用，无需安装 SDK。

💻 步骤 3：第一个程序

Python 示例

创建文件 hello_gemini.py：

python

import google.generativeai as genai
import os

# 配置 API 密钥
genai.configure(api_key=os.environ.get('GEMINI_API_KEY'))

# 创建模型实例
model = genai.GenerativeModel('gemini-3.0-pro')

# 生成内容
response = model.generate_content('请用一句话介绍 Gemini 3.0 的核心特性')

# 打印结果
print(response.text)

运行程序：

bash

# 设置环境变量
export GEMINI_API_KEY='your-api-key-here'

# 运行程序
python hello_gemini.py

JavaScript 示例

创建文件 hello_gemini.js：

javascript

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

// 配置 API 密钥
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

async function run() {
  // 创建模型实例
  const model = genAI.getGenerativeModel({ model: "gemini-3.0-pro" });

  // 生成内容
  const prompt = "请用一句话介绍 Gemini 3.0 的核心特性";
  const result = await model.generateContent(prompt);
  const response = await result.response;
  
  // 打印结果
  console.log(response.text());
}

run();

运行程序：

bash

# 设置环境变量
export GEMINI_API_KEY='your-api-key-here'

# 运行程序（Node.js）
node hello_gemini.js

REST API 示例

使用 cURL 直接调用：

bash

curl -X POST \
  "https://generativelanguage.googleapis.com/v1/models/gemini-3.0-pro:generateContent?key=YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [{
        "text": "请用一句话介绍 Gemini 3.0 的核心特性"
      }]
    }]
  }'

🎨 步骤 4：多模态示例

文本 + 图片分析

python

import google.generativeai as genai
from PIL import Image

genai.configure(api_key='YOUR_API_KEY')
model = genai.GenerativeModel('gemini-3.0-pro')

# 加载图片
img = Image.open('photo.jpg')

# 文本 + 图片输入
response = model.generate_content([
    "这张图片中有什么？请详细描述",
    img
])

print(response.text)

视频分析（Gemini 3.0 新功能）

python

import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')
model = genai.GenerativeModel('gemini-3.0-pro')

# 上传视频文件
video_file = genai.upload_file('video.mp4')

# 分析视频内容
response = model.generate_content([
    "总结这个视频的主要内容，提取关键信息",
    video_file
])

print(response.text)

🔧 步骤 5：高级配置

温度和采样参数

python

generation_config = {
    "temperature": 0.7,        # 控制随机性 (0-1)
    "top_p": 0.95,            # 核采样参数
    "top_k": 40,              # Top-K 采样
    "max_output_tokens": 2048, # 最大输出长度
}

model = genai.GenerativeModel(
    'gemini-3.0-pro',
    generation_config=generation_config
)

安全设置

python

safety_settings = [
    {
        "category": "HARM_CATEGORY_HARASSMENT",
        "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
]

model = genai.GenerativeModel(
    'gemini-3.0-pro',
    safety_settings=safety_settings
)

流式响应

python

response = model.generate_content(
    "写一篇关于人工智能未来的文章",
    stream=True
)

for chunk in response:
    print(chunk.text, end='')

🧠 深度思考模式（Deep Think）

Gemini 3.0 的独特功能 - 启用深度推理：

python

# 启用深度思考模式
model = genai.GenerativeModel(
    'gemini-3.0-pro',
    generation_config={
        "thinking_mode": "deep",  # 启用深度思考
        "show_reasoning": True     # 显示推理过程
    }
)

response = model.generate_content(
    "证明：对于所有大于2的质数p，p^2 + 2 不是质数"
)

# 查看推理过程
print("推理过程：")
print(response.reasoning_steps)

# 最终答案
print("\n最终答案：")
print(response.text)

🤖 智能代理功能

使用函数调用实现智能代理：

python

import google.generativeai as genai

# 定义工具函数
def get_weather(location: str) -> str:
    """获取指定位置的天气信息"""
    # 实际应用中调用真实的天气 API
    return f"{location}的天气：晴天，温度 22°C"

def book_restaurant(name: str, time: str, people: int) -> str:
    """预订餐厅"""
    return f"已预订{name}餐厅，时间：{time}，人数：{people}"

# 配置函数调用
tools = [get_weather, book_restaurant]

model = genai.GenerativeModel(
    'gemini-3.0-pro',
    tools=tools
)

# 对话
chat = model.start_chat()
response = chat.send_message(
    "查一下北京明天的天气，如果晴天就帮我订一个餐厅，晚上7点，2个人"
)

print(response.text)

📚 实用示例集

代码生成与解释

python

# 代码生成
response = model.generate_content(
    "用 Python 编写一个二叉树的层序遍历算法，包含注释"
)
print(response.text)

# 代码解释
code = """
def quick_sort(arr):
    if len(arr) <= 1:
        return arr
    pivot = arr[len(arr) // 2]
    left = [x for x in arr if x < pivot]
    middle = [x for x in arr if x == pivot]
    right = [x for x in arr if x > pivot]
    return quick_sort(left) + middle + quick_sort(right)
"""

response = model.generate_content(
    f"请详细解释这段代码的工作原理：\n\n{code}"
)
print(response.text)

文档分析

python

# 分析 PDF 文档
pdf_file = genai.upload_file('document.pdf')

response = model.generate_content([
    "总结这份文档的主要内容，提取关键信息和数据",
    pdf_file
])

print(response.text)

长上下文处理

python

# 分析整个代码仓库
with open('large_codebase.txt', 'r') as f:
    codebase = f.read()  # 可以是数百万 token

response = model.generate_content(
    f"分析这个代码库，找出潜在的性能问题和安全漏洞：\n\n{codebase}"
)

print(response.text)

❓ 常见问题

如何处理 API 限流？

python

import time
from google.api_core import retry

@retry.Retry(predicate=retry.if_exception_type(Exception))
def generate_with_retry(prompt):
    try:
        response = model.generate_content(prompt)
        return response.text
    except Exception as e:
        print(f"请求失败，重试中... {e}")
        time.sleep(2)
        raise

result = generate_with_retry("你好，Gemini!")

如何处理大文件上传？

python

# 分块上传大文件
import google.generativeai as genai

# 上传大文件（自动分块）
video_file = genai.upload_file(
    'large_video.mp4',
    display_name='教学视频'
)

# 等待处理完成
while video_file.state.name == "PROCESSING":
    print('处理中...')
    time.sleep(10)
    video_file = genai.get_file(video_file.name)

# 使用文件
response = model.generate_content([video_file, "分析这个视频"])

如何管理成本？

python

# 使用 token 计数
response = model.generate_content(
    "介绍人工智能",
    generation_config={"max_output_tokens": 500}  # 限制输出长度
)

# 查看使用情况
print(f"输入 tokens: {response.usage_metadata.prompt_token_count}")
print(f"输出 tokens: {response.usage_metadata.candidates_token_count}")
print(f"总计: {response.usage_metadata.total_token_count}")

🎯 最佳实践

1. 提示词工程

python

# ❌ 不好的提示词
response = model.generate_content("写代码")

# ✅ 好的提示词
response = model.generate_content("""
请用 Python 编写一个函数，实现以下功能：
1. 接收一个整数列表作为参数
2. 返回列表中的所有质数
3. 包含完整的错误处理
4. 添加类型提示和文档字符串
5. 时间复杂度应该优化到 O(n√m)，其中 m 是列表中的最大值
""")

2. 错误处理

python

try:
    response = model.generate_content(prompt)
    print(response.text)
except ValueError as e:
    print(f"内容被安全过滤器拦截: {e}")
except Exception as e:
    print(f"发生错误: {e}")

3. 环境变量管理

python

# 使用 .env 文件
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv('GEMINI_API_KEY')

genai.configure(api_key=api_key)

创建 .env 文件：

GEMINI_API_KEY=your_api_key_here

添加到 .gitignore：

.env

📖 下一步

恭喜！你已经掌握了 Gemini 3.0 的基础使用。接下来你可以：

🔗 相关资源

Google AI Studio - 在线测试平台
API 参考文档 - 完整 API 说明
示例代码库 - 官方示例
开发者论坛 - 社区支持

遇到问题？ 查看常见问题解答或在 GitHub Issues 提问

快速开始指南 ​

📋 前置要求 ​

🔑 步骤 1：获取 API 密钥 ​

方法一：Google AI Studio（推荐新手） ​

方法二：Google Cloud Console（企业用户） ​

🚀 步骤 2：安装 SDK ​

Python ​

Node.js / JavaScript ​

Go ​

其他语言 ​

💻 步骤 3：第一个程序 ​

Python 示例 ​

JavaScript 示例 ​

REST API 示例 ​

🎨 步骤 4：多模态示例 ​

文本 + 图片分析 ​

视频分析（Gemini 3.0 新功能） ​

🔧 步骤 5：高级配置 ​

温度和采样参数 ​

安全设置 ​

流式响应 ​

🧠 深度思考模式（Deep Think） ​

🤖 智能代理功能 ​

📚 实用示例集 ​

代码生成与解释 ​

文档分析 ​

长上下文处理 ​

❓ 常见问题 ​

如何处理 API 限流？ ​

如何处理大文件上传？ ​

如何管理成本？ ​

🎯 最佳实践 ​

1. 提示词工程 ​

2. 错误处理 ​

3. 环境变量管理 ​

📖 下一步 ​

🔗 相关资源 ​

快速开始指南

📋 前置要求

🔑 步骤 1：获取 API 密钥

方法一：Google AI Studio（推荐新手）

方法二：Google Cloud Console（企业用户）

🚀 步骤 2：安装 SDK

Python

Node.js / JavaScript

Go

其他语言

💻 步骤 3：第一个程序

Python 示例

JavaScript 示例

REST API 示例

🎨 步骤 4：多模态示例

文本 + 图片分析

视频分析（Gemini 3.0 新功能）

🔧 步骤 5：高级配置

温度和采样参数

安全设置

流式响应

🧠 深度思考模式（Deep Think）

🤖 智能代理功能

📚 实用示例集

代码生成与解释

文档分析

长上下文处理

❓ 常见问题

如何处理 API 限流？

如何处理大文件上传？

如何管理成本？

🎯 最佳实践

1. 提示词工程

2. 错误处理

3. 环境变量管理

📖 下一步

🔗 相关资源