如何使用 Gemini 3 API：开发者全指南 (2026)

如何使用 Gemini 3 API：2026年开发者全攻略

Google 的 Gemini 3 是其多模态 AI 模型家族的最新一代产品，在推理、代码生成、多模态理解和指令遵循方面带来了显著提升。无论你是正在开发聊天机器人、内容生成工具、代码助手还是多模态应用，Gemini 3 API 都能提供强大的底层支持。

本指南涵盖了入门所需的一切：身份验证、Python 和 JavaScript 的 API 调用、多模态输入、流式传输、函数调用（Function Calling）以及定价信息。

Gemini 3 模型版本

模型	上下文窗口 (Context Window)	最佳用途	速度
Gemini 3 Ultra	2M tokens	复杂推理、研究、编程	慢
Gemini 3 Pro	2M tokens	平衡质量与速度	中等
Gemini 3 Flash	1M tokens	快速响应、高吞吐量	快
Gemini 3 Flash Lite	512K tokens	成本优化、简单任务	极快

前提条件

1. Google Cloud 账号 或 Google AI Studio 账号
2. 来自 Google AI Studio 的 API key
3. Python 3.9+ 或 Node.js 18+
4. Google Generative AI SDK

第一步：获取 API Key

获取 API key 最快的方法：

1. 访问 Google AI Studio
2. 点击 Get API Key
3. 选择或创建一个 Google Cloud 项目
4. 复制生成的 API key

对于生产环境使用，请在 Google Cloud Console 的“API 和服务 > 凭据”中创建密钥。

第二步：安装 SDK

Python:

pip install google-generativeai

JavaScript/Node.js:

npm install @google/generative-ai

第三步：基础文本生成 (Python)

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

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

response = model.generate_content("用通俗易懂的语言解释量子计算")

print(response.text)

第四步：基础文本生成 (JavaScript)

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

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

async function generateText() {
  const result = await model.generateContent(
    "用通俗易懂的语言解释量子计算"
  );
  console.log(result.response.text());
}

generateText();

第五步：多轮对话

创建一个聊天会话进行往返对话：

Python:

import google.generativeai as genai

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

chat = model.start_chat(history=[])

# 第一条消息
response = chat.send_message("我正在用 Python 构建 REST API。我应该使用哪个框架？")
print(response.text)

# 后续跟进
response = chat.send_message("你能给我看一个带有 POST 接口的基础 FastAPI 示例吗？")
print(response.text)

# 另一个跟进（会话上下文会被保留）
response = chat.send_message("现在加上 Pydantic 的输入验证")
print(response.text)

JavaScript:

const chat = model.startChat({
  history: [],
});

const result1 = await chat.sendMessage(
  "我正在用 Python 构建 REST API。我应该使用哪个框架？"
);
console.log(result1.response.text());

const result2 = await chat.sendMessage(
  "你能给我看一个带有 POST 接口的基础 FastAPI 示例吗？"
);
console.log(result2.response.text());

第六步：多模态输入（图像 + 文本）

Gemini 3 在理解图像与文本结合方面表现出色：

Python:

import google.generativeai as genai
from pathlib import Path

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

# 加载图像
image_path = Path("screenshot.png")
image_data = image_path.read_bytes()

response = model.generate_content([
    "分析这张 UI 截图，并就可访问性和易用性提出 3 条具体改进建议。",
    {
        "mime_type": "image/png",
        "data": image_data
    }
])

print(response.text)

JavaScript:

import fs from "fs";

const imageData = fs.readFileSync("screenshot.png");
const base64Image = imageData.toString("base64");

const result = await model.generateContent([
  "分析这张 UI 截图并提出 3 条具体改进建议。",
  {
    inlineData: {
      mimeType: "image/png",
      data: base64Image,
    },
  },
]);

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

第七步：流式响应

为了获得更好的用户体验，可以逐个 token 地流式传输响应：

Python:

import google.generativeai as genai

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

response = model.generate_content(
    "编写一份关于使用 GitHub Actions 设置 CI/CD 流水线的详细指南",
    stream=True
)

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

print()  # 最后换行

JavaScript:

const result = await model.generateContentStream(
  "编写一份关于使用 GitHub Actions 设置 CI/CD 流水线的详细指南"
);

for await (const chunk of result.stream) {
  process.stdout.write(chunk.text());
}
console.log();

第八步：函数调用 (Function Calling)

Gemini 3 支持函数调用，允许模型请求执行特定操作：

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

# 定义工具
tools = [
    {
        "function_declarations": [
            {
                "name": "get_weather",
                "description": "获取指定地点的当前天气",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "城市名称，例如 'San Francisco, CA'"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"],
                            "description": "温度单位"
                        }
                    },
                    "required": ["location"]
                }
            },
            {
                "name": "search_products",
                "description": "在目录中搜索产品",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "query": {
                            "type": "string",
                            "description": "搜索查询词"
                        },
                        "max_results": {
                            "type": "integer",
                            "description": "最大结果数量"
                        }
                    },
                    "required": ["query"]
                }
            }
        ]
    }
]

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

response = chat.send_message("东京现在的天气怎么样？")

# 检查模型是否想要调用函数
for part in response.parts:
    if hasattr(part, "function_call"):
        function_name = part.function_call.name
        function_args = dict(part.function_call.args)
        print(f"函数调用: {function_name}({function_args})")

        # 执行函数并返回结果
        if function_name == "get_weather":
            # 这里调用你实际的 API
            weather_result = {"temperature": 22, "condition": "多云"}

            response = chat.send_message({
                "function_response": {
                    "name": function_name,
                    "response": weather_result
                }
            })
            print(response.text)

第九步：系统指令 (System Instructions)

通过系统指令设置模型的行为：

model = genai.GenerativeModel(
    "gemini-3-pro",
    system_instruction="""你是一名精通 Python 和云架构的高级软件工程师。
    始终提供代码示例。更倾向于使用 FastAPI 而非 Flask。
    在所有 Python 代码中使用类型提示（Type Hints）。
    解释要保持简洁实用。"""
)

response = model.generate_content("我该如何实现速率限制 (Rate Limiting)？")
print(response.text)

第十步：安全设置

配置内容过滤阈值：

from google.generativeai.types import HarmCategory, HarmBlockThreshold

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

response = model.generate_content(
    "在此输入你的 Prompt",
    safety_settings={
        HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_NONE,
        HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
        HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT: HarmBlockThreshold.BLOCK_ONLY_HIGH,
        HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
    }
)

定价 (2026年2月)

模型	输入 (每 1M tokens)	输出 (每 1M tokens)	上下文缓存 (Context Caching)
Gemini 3 Ultra	$10.00	$30.00	$2.50/小时
Gemini 3 Pro	$2.50	$10.00	$0.625/小时
Gemini 3 Flash	$0.15	$0.60	$0.0375/小时
Gemini 3 Flash Lite	$0.04	$0.15	不适用

免费层级： Google AI Studio 提供了带有频率限制的丰厚免费额度（Pro 模型 15 RPM，Flash 模型 30 RPM）。

直接使用 REST API

如果你不想使用 SDK：

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro:generateContent?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{
        "text": "编写一个验证电子邮件地址的 Python 函数"
      }]
    }],
    "generationConfig": {
      "temperature": 0.7,
      "topK": 40,
      "topP": 0.95,
      "maxOutputTokens": 2048
    }
  }'

生成配置选项 (Generation Config)

参数	默认值	范围	描述
temperature	1.0	0.0-2.0	输出的随机性
topP	0.95	0.0-1.0	核采样 (Nucleus Sampling) 阈值
topK	40	1-100	Top-k 采样
maxOutputTokens	取决于模型	1-8192+	最大响应长度
stopSequences	[]	最多 5 个	停止生成的字符串列表
candidateCount	1	1-8	响应候选数量

错误处理

import google.generativeai as genai
from google.api_core import exceptions

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

try:
    response = model.generate_content("你的 Prompt")
    print(response.text)
except exceptions.InvalidArgument as e:
    print(f"无效请求: {e}")
except exceptions.ResourceExhausted as e:
    print(f"超出速率限制。请稍后重试: {e}")
except exceptions.PermissionDenied as e:
    print(f"API key 无效或权限不足: {e}")
except exceptions.InternalServerError as e:
    print(f"Google 服务器错误。请重试: {e}")
except Exception as e:
    # 检查内容是否被安全过滤器拦截
    if hasattr(response, 'prompt_feedback'):
        print(f"内容被拦截: {response.prompt_feedback}")
    else:
        print(f"发生意外错误: {e}")

最佳实践

1. 选择正确的模型：Flash 用于保证速度，Pro 用于保证质量，Ultra 用于复杂推理。
2. 设置合适的 Temperature：事实型或代码任务使用 0.0-0.3，创意任务使用 0.7-1.0。
3. 使用系统指令来设定一致的行为。
4. 实现流式传输，以提升聊天界面的用户体验。
5. 对于重复的 Prompt 使用上下文缓存以降低成本（适用于 Pro 和 Ultra）。
6. 在应用中妥善 处理安全过滤器拦截 的情况。
7. 针对速率限制错误 实现指数退避 (Exponential Backoff) 策略。
8. 使用函数调用，而不是尝试从文本中解析结构化输出。

结论

Gemini 3 API 为构建 AI 驱动的应用提供了一个强大且具有成本效益的选择。凭借其巨大的上下文窗口、强大的多模态能力和极具竞争力的定价（尤其是 Flash 版本），它是原型设计和生产环境的理想选择。

如果你在语言模型之外还需要 AI 媒体生成能力——例如图像生成、视频创建、数字人对话或语音合成——Hypereal AI 提供了与 Gemini 相辅相成的统一 API。你可以使用 Gemini 进行文本和推理，使用 Hypereal 制作视频和音频内容，这一切都可以通过简单的 API 调用和透明的定价来实现。