Gemini API 串接 10 分鐘上手:Node.js 完整範例

如果你想做小工具 / 自架 AI helper,Gemini API 是入門好選擇 — 免費額度大、文檔新、SDK 簡潔。

這篇是「從 0 到第一個 working response」的最小可行教學。我假設你會基本 JS,但沒用過任何 LLM API。

1. 拿 API key

去 https://aistudio.google.com/ ,用 Google 帳號登入。

左下「Get API key」→ 「Create API key」→ 選一個 Google Cloud project(或新建)→ 拿到一串 AIza... 開頭的 key。

重點:

• 不要 commit 到 git(放 .env)
• 不要分享(任何人拿到都能花你的 quota)

存到 .env:

GEMINI_API_KEY=AIza你的key

2. 安裝 SDK

npm install @google/genai
npm install dotenv  # 讀 .env

3. 第一個 hello world

新建 hello.js:

import "dotenv/config";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: "gemini-2.0-flash-exp",
  contents: "用 50 字介紹台北的夜市文化",
});

console.log(response.text);

跑:

node hello.js

不出意外,你會看到 Gemini 介紹台北夜市的 50 字段落。

第一個 working response,3 行程式碼。

4. 加上 streaming(打字機效果)

Hello world 是「等完整 response 才印」,實際 app 通常要「打字機效果」(token 一個個出來)。

import "dotenv/config";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const stream = await ai.models.generateContentStream({
  model: "gemini-2.0-flash-exp",
  contents: "寫一首關於蜂蜜的短詩,4 行",
});

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

差別只在 generateContent → generateContentStream,然後用 for await loop chunks。

5. 多輪對話(chat session)

如果要做 chatbot,需要保留 history:

const chat = ai.chats.create({
  model: "gemini-2.0-flash-exp",
});

const r1 = await chat.sendMessage({ message: "我是 VTuber 創作者,想知道台北哪裡有 maid cafe" });
console.log("AI:", r1.text);

const r2 = await chat.sendMessage({ message: "上面那家最便宜的是哪間?" });
console.log("AI:", r2.text);
// Gemini 知道「上面那家」指的是 r1 的回應

chat.sendMessage 自動帶上 history,Gemini 知道脈絡。比手動 push messages array 簡潔。

6. 多模態:傳圖片給 Gemini 分析

Gemini 強項之一是多模態 — 圖片直接丟它分析。

import { GoogleGenAI } from "@google/genai";
import fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const imageBytes = fs.readFileSync("./screenshot.png");
const imageBase64 = imageBytes.toString("base64");

const response = await ai.models.generateContent({
  model: "gemini-2.0-flash-exp",
  contents: [
    {
      role: "user",
      parts: [
        { text: "這張截圖在做什麼?用繁體中文回答。" },
        { inlineData: { mimeType: "image/png", data: imageBase64 } },
      ],
    },
  ],
});

console.log(response.text);

Gemini 會描述截圖內容。可用於:

• VTuber 直播自動截圖找精華
• 自動寫 alt text(無障礙)
• 影片縮圖選擇

7. JSON mode(structured output)

如果你要 AI 出固定 schema 的 JSON,用 responseMimeType:

const response = await ai.models.generateContent({
  model: "gemini-2.0-flash-exp",
  contents: "從這段文字抽 3 個 tags(中文,每個 2-4 字): 我用 Suno 寫了 30 天 AI 音樂,發現整理流程比創作流程重要",
  config: {
    responseMimeType: "application/json",
    responseSchema: {
      type: "object",
      properties: {
        tags: {
          type: "array",
          items: { type: "string" },
          minItems: 3,
          maxItems: 3,
        },
      },
      required: ["tags"],
    },
  },
});

const data = JSON.parse(response.text);
console.log(data.tags);
// [ 'AI音樂', '工作流程', '創作整理' ]

這個對「文章自動標 tag」、「自動分類」、「萃取 metadata」超好用。

8. 錯誤處理

實戰要包 try-catch:

try {
  const response = await ai.models.generateContent({ ... });
  console.log(response.text);
} catch (e) {
  if (e.status === 429) {
    console.error("超過 rate limit,等 1 分鐘再試");
  } else if (e.status === 400) {
    console.error("Prompt 有問題:", e.message);
  } else {
    console.error("未知錯誤:", e);
  }
}

常見錯誤碼:

• 429:rate limit(每分鐘 request 太多)
• 400:prompt 內容違規 / token 太長
• 401:API key 錯
• 503:Google 服務暫時不穩

9. 成本控管

Gemini Flash 是最便宜的模型,但對大量 request 還是要監控:

// 每次 request 後印 usage
const response = await ai.models.generateContent({ ... });
console.log("Tokens used:", response.usageMetadata);
// { promptTokenCount: 25, candidatesTokenCount: 89, totalTokenCount: 114 }

把這些累計起來,部署到 production 前先估每月成本。免費額度炸掉前你會收到 email warning。

結論:Gemini API 適合「快速做工具」

我用 Gemini API 做過:

• DonBee 後台自動 tag suggestion(寫文章時 AI 建議標籤)
• 自動文章描述生成(meta description)
• 直播截圖分析(找精華片段)

每個都只用 50-100 行 JS,Free tier 跑得起來。

下一篇我會分享 Claude API 完整實戰(已寫,接的是 Claude Code 直接用 Anthropic API 那部分)。

如果這個 API 系列對你有幫助,Discord(支持冬蜜彈窗)有更深入的問答區。