Gemini API Node.js / JavaScript 調用教學：@google/genai 安裝、流式輸出與函數調用

本文根據 Gemini API 官方文檔（Quickstart、Text generation、Interactions API、Using Gemini API keys、Files API）和官方 SDK 倉庫 googleapis/js-genai 整理，資料核對於 2026-10-10。示例代碼基於官方示例改寫並加了中文註釋。

適用於誰

• 用 Node.js 或 TypeScript 寫後端、腳本，想接入 Gemini 的開發者；
• 搜「gemini api nodejs」「gemini api javascript」「@google/genai」的人；
• 想在網頁裏直接調 Gemini，但不確定密鑰該放哪裏的前端開發者。

Python 版見本站《Gemini API Python 調用教學：安裝 google-genai SDK、流式輸出、多輪對話與傳圖片》，兩篇的概念一致，這裏側重 JavaScript 的寫法和函數調用。

結論先說

1. 官方 SDK 的包名是 @google/genai：npm install @google/genai。舊版 SDK @google/generative-ai 官方已標註為不再積極維護，並提供了遷移指南。
2. 入口是 GoogleGenAI 類：const ai = new GoogleGenAI({})，然後調用 ai.interactions.create({ model, input })，文本結果在 interaction.output_text。
3. 參數名用下劃線：Interactions API 的字段在 JavaScript 裏也是 previous_interaction_id、system_instruction、generation_config 這種寫法。
4. 生產環境不要把密鑰放進瀏覽器：官方明確提示寫在客戶端代碼裏的密鑰可以被提取，要在自己的伺服器上調用。
5. 函數調用是一個循環：模型返回 function_call → 你執行函數 → 把結果作為 function_result 傳回去 → 直到模型不再要求調用。

一、安裝與配置

bash
mkdir gemini-node && cd gemini-node
npm init -y
npm pkg set type=module          # 用 ES 模組，才能寫 import 和頂層 await
npm install @google/genai

export GEMINI_API_KEY="你的API密鑰"   # Windows PowerShell: $env:GEMINI_API_KEY="你的API密鑰"

• Node.js 版本：SDK 倉庫 README 要求 20 及以上，並預告 3.0.0 版起需要 22 及以上。
• 官方說明 Interactions API 需要 @google/genai 2.3.0 及以上。
• 密鑰的申請和環境變量設定見本站《Gemini API Key 怎麼獲取：在 AI Studio 創建密鑰、設定環境變量與安全限制》。

二、第一個請求

新建 index.js：

javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});   // 自動讀取環境變量裏的密鑰

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  system_instruction: "你是一個簡潔的中文助手。",
  input: "用三句話解釋什麼是向量數據庫",
  generation_config: { thinking_level: "low" },   // 可選 low / medium / high
});

console.log(interaction.output_text);
console.log(interaction.usage);   // 輸入、輸出、思考 token 數

運行 node index.js。說明：

• 需要顯式傳密鑰時寫 new GoogleGenAI({ apiKey: "你的API密鑰" })，官方建議只在沒法用環境變量時這樣做；
• output_text 是便捷屬性，完整過程在 interaction.steps 數組裏；
• temperature、top_p、top_k 在 Gemini 3.6 Flash、3.5 Flash-Lite 及之後的模型上已棄用並被忽略，不用再傳。

三、流式輸出

javascript
const stream = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "寫一段 200 字左右的秋天散文",
  stream: true,
});

for await (const event of stream) {
  // 文本片段在 step.delta 事件裏
  if (event.event_type === "step.delta" && event.delta.type === "text") {
    process.stdout.write(event.delta.text);
  }
}

四、多輪對話

把上一輪的 id 傳給 previous_interaction_id，歷史由伺服器管理：

javascript
const first = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "我家裏有 2 只狗。",
});

const second = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "那我家一共有多少隻爪子？",
  previous_interaction_id: first.id,
});
console.log(second.output_text);

• 伺服器只接續對話歷史，system_instruction、generation_config、tools 每一輪都要重新傳；
• 交互記錄預設儲存在伺服器上，官方寫明免費層保留 1 天、付費層保留 55 天；
• 不想儲存就傳 store: false，自己把完整歷史（含模型返回的全部步驟）放進 input，寫法見 Python 版教學裏的「無狀態」一節，結構完全相同。

五、傳圖片

javascript
const uploaded = await ai.files.upload({
  file: "photo.jpg",
  config: { mimeType: "image/jpeg" },
});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "這張圖裏有什麼？用中文描述。" },
    { type: "image", uri: uploaded.uri, mime_type: uploaded.mimeType },
  ],
});
console.log(interaction.output_text);

小文件也可以用 fs.readFileSync("photo.jpg").toString("base64") 讀成 base64，寫成 { type: "image", data: 這段base64, mime_type: "image/jpeg" }。官方的界限：整個請求超過 100 MB（PDF 為 50 MB）必須走 Files API；上載的文件儲存 48 小時。

六、函數調用：讓模型用你的函數

函數調用（function calling）的流程是：你聲明函數的名字和參數，模型決定什麼時候調用並給出參數，你在本地執行後把結果傳回去。下面是官方快速開始裏的循環寫法：

javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

// 1. 聲明工具：名字、說明、參數（JSON Schema）
const weatherTool = {
  type: "function",
  name: "get_current_temperature",
  description: "查詢指定城市當前的氣溫。",
  parameters: {
    type: "object",
    properties: {
      location: { type: "string", description: "城市名，例如 北京" },
    },
    required: ["location"],
  },
};

// 2. 你自己的函數實現（這裏用假數據）
const availableFunctions = {
  get_current_temperature: ({ location }) => ({
    location, temperature: "22", unit: "celsius",
  }),
};

let input = "北京現在多少度？";
let previousId = null;
let interaction;

while (true) {
  interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input,
    tools: [weatherTool],                 // 每一輪都要帶上工具聲明
    previous_interaction_id: previousId,
  });

  // 3. 找出模型要求調用的函數，逐個執行
  const functionResults = [];
  for (const step of interaction.steps) {
    if (step.type === "function_call") {
      const result = availableFunctions[step.name](step.arguments);
      functionResults.push({
        type: "function_result",
        name: step.name,
        call_id: step.id,                 // 和這次調用的 id 對應
        result: [{ type: "text", text: JSON.stringify(result) }],
      });
    }
  }

  if (functionResults.length === 0) break;   // 模型不再調用函數，結束

  // 4. 把執行結果作為下一輪輸入傳回去
  input = functionResults;
  previousId = interaction.id;
}

console.log(interaction.output_text);

官方說明：模型要求調用函數時，這一輪返回的 status 是 requires_action；你提交結果後，才會得到 completed 的最終回答。Google 搜尋、代碼執行這類內置工具不需要這個循環，在 tools 裏寫 { type: "google_search" } 即可，由伺服器端執行。

七、為什麼不能在瀏覽器裏直接用密鑰

SDK 可以在瀏覽器裏初始化，但官方在 README 和 API key 頁都給了同樣的警告：

• 編譯進網頁或手機應用的密鑰可以被用戶提取出來；
• 正確做法是在自己的後端服務裏調用 Gemini API，前端只和自己的後端通信；
• 在 AI Studio 的 Build 模式裏生成的應用，官方說明密鑰會自動配置成伺服器端的密文（Secret），不會出現在客戶端代碼裏。

常見問題

Q：報 Cannot use import statement outside a module？

package.json 裏沒有 "type": "module"。按第一節執行 npm pkg set type=module，或把文件擴展名改成 .mjs。

Q：要用 TypeScript 怎麼辦？

包名和導入寫法相同。官方對這個 SDK 的正式稱呼就是「Google Gen AI SDK for TypeScript and JavaScript」，兩種語言共用一個包。

Q：舊代碼裏的 ai.models.generateContent 還能用嗎？

能。官方把 generateContent 稱為 legacy 接口但仍完全支持，寫法是 await ai.models.generateContent({ model, contents })，結果在 response.text；多輪對話用 ai.chats.create({ model })。新項目官方建議用 Interactions API。

Q：調用報錯怎麼排查？

先用 try { ... } catch (e) { console.error(e) } 把完整錯誤打印出來，看 HTTP 狀態碼。429 是觸發速率限制，見本站《Gemini API 429 錯誤怎麼解決：RESOURCE_EXHAUSTED 的原因與 400 / 403 / 503 排查表》。

Q：想讓輸出一定是 JSON？

用結構化輸出，配合 Zod 校驗，見本站《Gemini 結構化輸出（Structured Output）怎麼用：JSON Schema、Pydantic 與 Zod 示例》。

參考資料

• Gemini API quickstart（官方）：https://ai.google.dev/gemini-api/docs/quickstart
• Gemini API quickstart（generateContent 版，官方）：https://ai.google.dev/gemini-api/docs/generate-content/quickstart
• Text generation（官方）：https://ai.google.dev/gemini-api/docs/text-generation
• Interactions API（官方）：https://ai.google.dev/gemini-api/docs/interactions-overview
• Gemini API libraries（官方）：https://ai.google.dev/gemini-api/docs/libraries
• Migrate to the Google GenAI SDK（官方）：https://ai.google.dev/gemini-api/docs/migrate
• Using Gemini API keys（官方）：https://ai.google.dev/gemini-api/docs/api-key
• Files API（官方）：https://ai.google.dev/gemini-api/docs/files
• Models（官方）：https://ai.google.dev/gemini-api/docs/models
• googleapis/js-genai（官方 SDK 倉庫）：https://github.com/googleapis/js-genai