Gemini API 怎么接 Next.js？从 API Key 到服务端 Route Handler + 流式

Google Gemini API 接 Next.js 的逻辑和接 OpenAI 一样：key 放服务端、用 Route Handler 中转、前端只调你自己的接口。Gemini 有免费额度，适合做 Demo，但 key 一样不能漏到前端。

第一步：拿 Key + 装 SDK

去 Google AI Studio 申请 API Key（注意它的免费额度和速率限制）。装官方 SDK：

npm install @google/generative-ai

.env.local（不加 NEXT_PUBLIC_）：

GEMINI_API_KEY=xxxxx

第二步：服务端 Route Handler

新建 app/api/gemini/route.ts：

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

export const runtime = "nodejs";
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);

export async function POST(req: Request) {
  const { prompt } = await req.json();
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" }); // 以官方当前模型为准
  const result = await model.generateContent(prompt);
  return Response.json({ text: result.response.text() });
}

前端 fetch("/api/gemini", ...)，key 不出服务端。

第三步：流式返回

const result = await model.generateContentStream(prompt);
const encoder = new TextEncoder();
return new Response(new ReadableStream({
  async start(controller) {
    for await (const chunk of result.stream) {
      controller.enqueue(encoder.encode(chunk.text()));
    }
    controller.close();
  },
}), { headers: { "Content-Type": "text/plain; charset=utf-8" } });

常见报错和修复

• 400 API key not valid：key 错或没读到 → 检查 .env.local、重启 dev。
• 403 / PERMISSION_DENIED：key 没开对应 API，或地区/项目限制 → 在 Google AI Studio / Cloud 确认 key 权限。
• 429 RESOURCE_EXHAUSTED：超免费额度或 RPM/TPM 限制 → 降速、加重试退避、或换更高配额。
• 生产读不到：Vercel 没配 GEMINI_API_KEY → 补环境变量并重新部署。

OpenAI vs Gemini 接入差异（一句话）

调用结构几乎一样（key + 服务端中转 + 流式），主要差别在 SDK 包名和方法名：OpenAI 是 openai + chat.completions.create，Gemini 是 @google/generative-ai + generateContent。换供应商主要改这层。

让 Codex 辅助

我在 Next.js 接 Gemini API 报 [贴报错]。
请判断是 key 无效、权限、还是配额问题，给出修复，并确认我的 key 没暴露在前端。

风险提醒

• key 只在服务端，泄露立刻在 Google AI Studio 吊销换新。
• 免费额度有限，给 /api/gemini 加频率限制，别被人刷爆配额。

相关工具

• 报错解释器
• Codex 工具页
• 项目报价助手

相关 AI 接入

接其他模型 / 管好 key 一起看：

• OpenAI API 接入 Next.js 怎么做
• Claude API 怎么接入 Next.js
• AI API Key 怎么安全管理

免责声明

本文 SDK 用法对应 Google Generative AI 与 Next.js 的通用行为；具体模型名、免费额度、限额以 Google AI 官方文档为准，涉及客户密钥时需明确授权并人工复核。