🔗 AI API 串接實戰

Q: 我該直接呼叫 API 還是用 LangChain？

簡單場景（單次對話、簡單任務）直接用 API 更輕量。複雜場景（Agent、RAG、多步驟 Chain）用 [LangChain](/tech/langchain-guide) 框架能省大量開發時間。建議先熟悉原生 API，再學框架。

OpenAI、Claude、Gemini API 完全指南——從第一次呼叫到生產部署。

🔗 為什麼要學 API 串接？

用 ChatGPT 網頁版聊天很方便，但工程師要把 AI 融入產品，必須透過 API。

💡 一句話理解 API = 讓你的程式碼直接和 AI 大腦對話的通道。網頁版是「人和 AI 聊天」，API 是「程式碼和 AI 聊天」。

API vs 網頁版

面向	網頁版	API
使用者	人類手動操作	程式碼自動呼叫
擴展性	一次一個對話	每秒數百次呼叫
客製化	受限於 UI 功能	完全自由控制
整合	獨立使用	嵌入任何系統
成本	月費制	按 Token 計費

🚀 快速開始：三大 API 比較

2026 主流 AI API 一覽

特色	OpenAI	Anthropic (Claude)	Google (Gemini)
旗艦模型	GPT-5.4	Claude Sonnet 4.6	Gemini 2.5 Pro
Context Window	128K tokens	200K tokens	1M tokens
Streaming	✅ SSE	✅ SSE	✅ SSE
Function Calling	✅ 穩定	✅ 穩定	✅ 穩定
Vision	✅	✅	✅
定價（輸入）	$2.50/M tokens	$3.00/M tokens	$1.25/M tokens
定價（輸出）	$10.00/M tokens	$15.00/M tokens	$5.00/M tokens
免費額度	❌	❌	✅ 有免費層
最佳場景	通用、生態系最大	長文、程式碼	長 context、低成本

🔧 Step 1：取得 API Key

OpenAI

1. 前往 platform.openai.com
2. 註冊/登入 → Settings → API Keys
3. 點擊「Create new secret key」
4. 命名（如 "my-project-key"）→ 複製保存
5. 設定用量上限（Billing → Usage limits）

Anthropic (Claude)

1. 前往 console.anthropic.com
2. 註冊/登入 → API Keys
3. 點擊「Create Key」
4. 複製保存（只顯示一次！）

Google (Gemini)

1. 前往 aistudio.google.com
2. 點擊「Get API Key」
3. 選擇 Google Cloud 專案
4. 複製保存

⚠️ 安全守則

API Key 絕對不要寫在程式碼裡或推上 Git

使用環境變數（.env 檔案）管理

設定每月用量上限，防止意外帳單爆炸

正式環境用 Secret Manager（AWS Secrets Manager、GCP Secret Manager）

💻 Step 2：第一次 API 呼叫

OpenAI（Python）

import openai
import os

client = openai.OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "你是一位專業的台灣科技記者，用繁體中文回答。"},
        {"role": "user", "content": "用 3 句話解釋什麼是 RAG。"}
    ],
    temperature=0.7,     # 創意程度（0=精確, 1=創意）
    max_tokens=500,      # 最大輸出長度
)

print(response.choices[0].message.content)
# Token 用量
print(f"輸入: {response.usage.prompt_tokens} tokens")
print(f"輸出: {response.usage.completion_tokens} tokens")

Anthropic (Claude)

import anthropic
import os

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

response = client.messages.create(
    model="claude-sonnet-4-20260514",
    max_tokens=500,
    system="你是一位專業的台灣科技記者，用繁體中文回答。",
    messages=[
        {"role": "user", "content": "用 3 句話解釋什麼是 RAG。"}
    ]
)

print(response.content[0].text)
print(f"輸入: {response.usage.input_tokens} tokens")
print(f"輸出: {response.usage.output_tokens} tokens")

Google Gemini

import google.generativeai as genai
import os

genai.configure(api_key=os.environ["GEMINI_API_KEY"])
model = genai.GenerativeModel("gemini-2.5-pro")

response = model.generate_content(
    "用 3 句話解釋什麼是 RAG。",
    generation_config=genai.GenerationConfig(
        temperature=0.7,
        max_output_tokens=500,
    )
)

print(response.text)
print(f"Token 用量: {response.usage_metadata}")

JavaScript / Node.js

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "你是一位專業的台灣科技記者。" },
    { role: "user", content: "用 3 句話解釋什麼是 RAG。" },
  ],
  temperature: 0.7,
  max_tokens: 500,
});

console.log(response.choices[0].message.content);

🌊 Step 3：Streaming（串流回應）

一般呼叫要等 AI 全部生成完才回傳。Streaming 讓你逐字接收，使用者體驗更好。

Python Streaming

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "寫一篇 300 字的 AI 趨勢分析"}
    ],
    stream=True  # 開啟串流
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

JavaScript SSE（前端即時顯示）

const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "寫一篇 AI 趨勢分析" }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || "";
  process.stdout.write(content); // 即時輸出
}

Claude Streaming

with client.messages.stream(
    model="claude-sonnet-4-20260514",
    max_tokens=1000,
    messages=[{"role": "user", "content": "寫一篇 AI 趨勢分析"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

🛡️ Step 4：錯誤處理

API 呼叫一定會失敗——網路問題、額度用完、模型過載。穩健的錯誤處理是生產環境的必備。

完整錯誤處理範例

import openai
import time

def call_ai(messages, max_retries=3):
    """帶有指數退避重試的 API 呼叫"""
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gpt-4o",
                messages=messages,
                timeout=30  # 30 秒逾時
            )
            return response.choices[0].message.content

        except openai.RateLimitError:
            # 429: 超過速率限制 → 等待後重試
            wait = 2 ** attempt  # 指數退避：1s, 2s, 4s
            print(f"速率限制，等待 {wait} 秒...")
            time.sleep(wait)

        except openai.APITimeoutError:
            # 請求逾時 → 重試
            print(f"請求逾時，重試 {attempt + 1}/{max_retries}")

        except openai.BadRequestError as e:
            # 400: 請求格式錯誤（不該重試）
            print(f"請求錯誤: {e}")
            raise  # 直接拋出，不重試

        except openai.AuthenticationError:
            # 401: API Key 錯誤（不該重試）
            print("API Key 無效！請檢查 OPENAI_API_KEY")
            raise

        except openai.APIError as e:
            # 500: 伺服器錯誤 → 重試
            wait = 2 ** attempt
            print(f"API 錯誤: {e}，等待 {wait} 秒重試...")
            time.sleep(wait)

    raise Exception("API 呼叫失敗，已達最大重試次數")

常見錯誤速查表

HTTP 狀態碼	意義	該怎麼辦
400	請求格式錯	檢查 request body，不重試
401	API Key 無效	檢查 Key，不重試
403	權限不足	檢查模型存取權限
429	速率限制	指數退避重試
500	伺服器錯誤	等待後重試
503	模型過載	等待後重試 or 切換模型

💰 Step 5：成本控制

Token 計算

import tiktoken

def count_tokens(text, model="gpt-4o"):
    """計算文字的 token 數量"""
    encoder = tiktoken.encoding_for_model(model)
    return len(encoder.encode(text))

# 範例
text = "這是一段測試文字，用來計算 token 數量。"
tokens = count_tokens(text)
print(f"Token 數: {tokens}")  # 中文大約每字 1-2 tokens

成本預估公式

每次呼叫成本 = (輸入 tokens × 輸入單價) + (輸出 tokens × 輸出單價)

範例（GPT-4o）：
輸入 1000 tokens × $2.50/M = $0.0025
輸出 500 tokens × $10.00/M = $0.005
單次成本 = $0.0075（約 NT$0.24）

每日 1000 次呼叫 = NT$240/天 = NT$7,200/月

省錢策略

策略	節省幅度	方法
使用小模型	50-80%	簡單任務用 GPT-4o-mini，複雜任務才用 GPT-4o
Prompt 精簡	20-40%	減少不必要的 system prompt 長度
快取回應	60-90%	相同問題直接回傳快取結果
設定 max_tokens	10-30%	限制輸出長度避免冗詞
Batch API	50%	非即時需求用批次 API（半價）

🔄 Step 6：多 Provider Fallback

生產環境不應該只依賴一家 API。當主要 Provider 故障時，自動切換到備用——這是 AI 設計模式中「優雅降級」的核心概念。

class AIClient:
    """多 Provider 自動切換的 AI 客戶端"""

    def __init__(self):
        self.providers = [
            {"name": "OpenAI", "call": self._call_openai},
            {"name": "Claude", "call": self._call_claude},
            {"name": "Gemini", "call": self._call_gemini},
        ]

    def chat(self, messages, max_tokens=1000):
        for provider in self.providers:
            try:
                result = provider["call"](messages, max_tokens)
                return {"provider": provider["name"], "content": result}
            except Exception as e:
                print(f"{provider['name']} 失敗: {e}，切換下一個...")
                continue
        raise Exception("所有 AI Provider 都失敗了")

    def _call_openai(self, messages, max_tokens):
        response = openai_client.chat.completions.create(
            model="gpt-4o", messages=messages, max_tokens=max_tokens
        )
        return response.choices[0].message.content

    def _call_claude(self, messages, max_tokens):
        # 轉換 message 格式（Claude 的 system 是獨立參數）
        system = next((m["content"] for m in messages if m["role"] == "system"), "")
        user_msgs = [m for m in messages if m["role"] != "system"]
        response = claude_client.messages.create(
            model="claude-sonnet-4-20260514",
            system=system, messages=user_msgs, max_tokens=max_tokens
        )
        return response.content[0].text

    def _call_gemini(self, messages, max_tokens):
        prompt = "\n".join(m["content"] for m in messages)
        response = gemini_model.generate_content(prompt)
        return response.text

📋 API 串接 Checklist

在你的專案上線前，確認以下項目：

✅ API Key 使用環境變數，不在程式碼中
✅ 設定了每月用量上限
✅ 有完整的錯誤處理和重試邏輯
✅ 有 Streaming 支援（如果是用戶面向）
✅ 有成本監控和預警
✅ 有 Fallback Provider
✅ 有 Request/Response 日誌記錄
✅ 設定了合理的 timeout

→ 學會呼叫 API 之後，下一步是讓 AI 輸出結構化資料。請看 Structured Output 指南。

❓ FAQ

OpenAI、Claude、Gemini API 怎麼選？

看場景：OpenAI 生態系和工具最豐富。Claude 的長文理解和程式碼能力最強，200K context 適合大型文件。Gemini 有 1M context 且價格最低，適合成本敏感場景。建議先用 OpenAI 開發，再根據需求評估其他。

API 呼叫一次要多少錢？

一次 GPT-4o 呼叫（1000 輸入 + 500 輸出 tokens）約 NT$0.24。用 GPT-4o-mini 只要 NT$0.03。中文大約每字 1-2 tokens。設定月用量上限避免帳單爆炸。

我該直接呼叫 API 還是用 LangChain？

簡單場景（單次對話、簡單任務）直接用 API 更輕量。複雜場景（Agent、RAG、多步驟 Chain）用 LangChain 框架能省大量開發時間。建議先熟悉原生 API，再學框架。

Streaming 有什麼好處？

使用者不用等 AI 全部生成完才看到回應，可以像打字一樣逐字出現。體感延遲從「等 3 秒看到一整段」變成「0.3 秒就開始看到文字」。用戶面向的產品幾乎都應該用 Streaming。

🔗 為什麼要學 API 串接？

API vs 網頁版

🚀 快速開始：三大 API 比較

2026 主流 AI API 一覽

🔧 Step 1：取得 API Key

OpenAI

Anthropic (Claude)

Google (Gemini)

💻 Step 2：第一次 API 呼叫

OpenAI（Python）

Anthropic (Claude)

Google Gemini

JavaScript / Node.js

🌊 Step 3：Streaming（串流回應）

Python Streaming

JavaScript SSE（前端即時顯示）

Claude Streaming

🛡️ Step 4：錯誤處理

完整錯誤處理範例

常見錯誤速查表

💰 Step 5：成本控制

Token 計算

成本預估公式

省錢策略

🔄 Step 6：多 Provider Fallback

📋 API 串接 Checklist

❓ FAQ

📚 延伸閱讀