AI Studio 與第一個 Gemini API 呼叫

Google AI Studio 是試用模型與建立 Gemini API 金鑰的開發入口。本篇從一個簡單提示詞開始，帶你建立獨立專案環境，分別用 Python 與 JavaScript 呼叫 API。完成後，你會知道網頁試跑、程式執行與帳號用量各自在哪裡確認，不再把消費者版 Gemini 的操作直接套程式式。

開始前：帳號、環境與驗證範圍

準備可使用 AI Studio 的 Google 帳號與一臺能執行 Python 的電腦；JavaScript 範例另需 Node.js。本系列主要用 Python，查證日的範例套件為 google-genai 2.23.0，JavaScript 使用 @google/genai 2.22.0。本機範例採語法與模擬服務驗證，尚未使用讀者的真實金鑰呼叫 Google；以下步驟提供完整連線驗收方式。

先讀提示詞設計與API 計費。Gemini 網頁訂閱、Google Workspace、CLI 的 Google 登入及 API 專案不是同一套計費入口。AI Studio 看得到某個模型，也不代表你的每個 API 專案都有相同額度；執行前確認金鑰屬於哪個專案，再檢視該專案的限制。

本篇跟隨當前官方快速入門的 Interactions API，使用 input 與 output_text。你可能在舊文章看到 models.generate_content、contents 與 response.text；那是另一條 API 介面，不要把兩者引數混在同一個呼叫中。既有程式要遷移時，先以官方遷移檔案逐項比對。

第一步：在 AI Studio 試好同一題

1. 開啟文末官方 AI Studio 入門連結，登入並確認目前帳號與專案。
2. 建立提示詞，選擇目前可用的文字模型，輸入下方範例後執行。
3. 檢視回覆是否真的列出三個欄位，並記錄選用模型的完整識別名稱。
4. 到 API Keys（金鑰）頁面建立或選取金鑰，確認它所屬的專案。
5. 若需要啟用計費，先閱讀方案與付款條件；本篇不要求為了第一個練習直接升級。

請用繁體中文列出整理活動公告時應核對的三個欄位。
每個欄位附一句用途說明，不假設任何特定活動已經公告。

預期得到日期、地點、報名等可檢查欄位。答案可以有不同選擇，但應符合三項與用途說明的格式。把這題保留下來，稍後在程式裡使用相同方向的提示詞，便能把環境問題與題目難度分開。

第二步：建立 Python 環境並設定金鑰

在新的練習資料夾建立虛擬環境，避免套件版本影響其他專案。Windows 使用以下命令；macOS 或 Linux 可用 python3 建立環境，之後以 .venv/bin/python 執行。版本固定是為了重現本篇，升級前再查官方 SDK 更新與相容性。

python -m venv .venv
.venv/Scripts/python.exe -m pip install google-genai==2.23.0
$env:GEMINI_API_KEY = Read-Host "貼上 AI Studio 金鑰" -MaskInput
$env:GEMINI_MODEL = "gemini-3.8-flash"

Read-Host 的 MaskInput 需要 PowerShell 7；其他環境請使用受控的秘密輸入方式設定變數。不要把金鑰寫程式式碼、截圖或提交到 Git。GEMINI_MODEL 只是本練習使用的模型識別字，若帳號不支援，改成 AI Studio 與官方模型清單共同確認可用的名稱。

把下面存成 first.py，使用虛擬環境的 Python 執行。程式明確檢查狀態與文字，避免把尚未完成或空白輸出當作成功。store=False 關閉這次 Interaction 的伺服器狀態儲存，不等於所有資料處理政策都被關閉；資料條款仍需另外確認。

import os
from google import genai

model = os.environ.get("GEMINI_MODEL", "gemini-3.8-flash")
with genai.Client(api_key=os.environ["GEMINI_API_KEY"]) as client:
    reply = client.interactions.create(
        model=model,
        input="請用繁體中文列出整理活動公告時應核對的三個欄位。",
        store=False,
    )
    if reply.status != "completed" or not reply.output_text:
        raise RuntimeError("回覆尚未完成或沒有文字，請檢查回傳狀態。")
    print(reply.output_text)

.venv/Scripts/python.exe first.py

第三步：用 JavaScript 做相同呼叫

JavaScript 範例在終端機由 Node.js 執行，檔案副檔名用 .mjs。不要把包含金鑰的範例直接放到公開網頁前端，因為瀏覽器下載到的程式與請求都能被使用者檢視。要做網站功能時，將 API 呼叫放在你控制的後端。

npm install @google/genai@2.22.0
node first.mjs

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

if (!process.env.GEMINI_API_KEY) throw new Error("請先設定 GEMINI_API_KEY");
const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const reply = await client.interactions.create({
  model: process.env.GEMINI_MODEL || "gemini-3.8-flash",
  input: "請用繁體中文列出整理活動公告時應核對的三個欄位。",
  store: false,
});
if (reply.status !== "completed" || !reply.output_text) throw new Error("回覆未完成或沒有文字");
console.log(reply.output_text);

執行前沿用已設定的 GEMINI_API_KEY 與 GEMINI_MODEL。成功後在終端機看到文字，再到 AI Studio 的用量頁確認對應專案有這次活動。用量顯示可能有更新時間差，單次沒有立即出現時先核對專案與時間，避免反覆重跑造成額外用量。

常見問題與下一步

「找不到 google 或 genai 模組」先確認安裝套件與執行程式使用同一個 Python。使用 .venv 的完整執行路徑可減少環境混淆；不要把舊的 google-generativeai 套件範例直接當成 google-genai 的用法。

「金鑰已貼上卻顯示未設定」環境變數通常隻影響目前終端機及它啟動的子程式。你若改從另一個編輯器視窗執行，需要在該環境提供變數。只檢查變數是否存在，不要為了除錯把完整金鑰印出來。

「回傳模型不存在或權限不足」確認完整模型名稱、API 路線、專案與帳號資格。模型的顯示名稱不一定等於程式識別字；也不能把 Gemini 網頁的模式名稱直接填進 model。保留錯誤碼，依錯誤分類處理，不要無限重試。

第一次成功後，記下 SDK 版本、模型、日期與使用的提示詞。接著閱讀檔案輸入與結構化輸出，把普通文字回覆改成可驗證的欄位；最後用檔案助理實作把輸入、驗證與儲存串成一個完整工具。

完成後的檢核

接著可以閱讀 CLI 認證、API 檔案與 JSON，把本篇的操作接到下一個工作流程。

返回 Gemini 教學總目錄

• AI 工具
• 教學
• Gemini CLI 與 API