第一支程式:呼叫 Claude API

你每個月付 20 美元的 Claude Pro 訂閱,在 claude.ai 上跟 Claude 聊得很愉快——但你想在自己的程式裡也用到 Claude,第一個反應通常是:「那我怎麼讓我的 Python 腳本去跟 Claude 講話?」

答案不是「把瀏覽器自動化去戳 claude.ai」,那條路又脆又慢,Anthropic 的使用條款也不允許。真正的做法是:用 Anthropic 提供的 API,直接在你的程式裡送請求、拿回應,完全繞過瀏覽器。訂閱和 API 是兩條平行的收費管道,互不干擾——這堂課就從這個區別開始。

這堂學什麼

• 訂閱 vs API 的本質差異:為什麼不能共用、各自適合哪些場景
• 在 Anthropic Console 建立 API Key,並用 .env + .gitignore 安全保存
• 安裝 Python SDK(anthropic)與 JavaScript SDK(@anthropic-ai/sdk)
• 用 messages.create() 送出第一個請求,完整可跑的雙語範例
• 解讀 API 回應物件:content、usage、stop_reason 各代表什麼
• 排解三個最常見的初學錯誤:401、429、以及 SDK 版本問題

觀念一:訂閱 vs API,兩條不同的管道

很多人第一次遇到這個問題:「我已經有 Claude Pro 了,為什麼還要另外付 API 費用?」

簡單說,兩者是完全獨立的產品:

圖:Claude API 官方文件(2026 年 7 月實況),來源:platform.claude.com

API 帳號要另外到 console.anthropic.com 建立,充值購買用量,才能拿到 API Key 開始呼叫。Pro 訂閱不會自動幫你開 API 存取權限。

這個設計不是刁難:訂閱走的是「登入帳號 + 對話介面」的授權,API 走的是「金鑰 + 按量計費」的授權,兩套系統的計費後台、額度、甚至資料保留政策都不一樣。所以你沒辦法拿 Claude.ai 的登入憑證去呼叫 API,反過來也一樣。想清楚這點,後面所有「為什麼要另外充值」「為什麼金鑰跟訂閱要分開管理」的疑問都會迎刃而解——它們本來就是兩個獨立的產品線。

觀念二:Token 是什麼,帳單怎麼算

在看模型表格之前,先弄清楚 API 的計費單位「token」——這個詞在整門課會一直出現。

Token 不等於字,也不等於一個英文單字。一個英文 token 大約是 4 個字元,一個中文字通常佔 1–2 個 token。實際上你不需要手動換算,Anthropic SDK 會在回應的 usage 物件裡直接告訴你消耗了幾個 input token、幾個 output token。

這裡有個實務重點:output token 的單價通常是 input 的 4 到 5 倍(對照上面模型表就看得出來),所以真正吃成本的往往是「Claude 回你多長」,而不是「你問得多長」。這也提醒你在設計 prompt 時,與其省輸入,不如想辦法讓輸出精簡。另外中文比英文更耗 token——同樣意思的一句話,中文可能用掉接近英文兩倍的 token 量,估算中文應用的帳單時要特別把這個係數算進去。

計費公式很簡單:

費用 = input_tokens × 輸入單價 + output_tokens × 輸出單價
(單價以「每百萬 token」計)

舉個具體例子:你用 claude-haiku-4-5 送了一個 200 token 的問題,Claude 回了 150 token 的答案:

費用 = (200 × $1.00 + 150 × $5.00) / 1,000,000
     = ($0.000200 + $0.000750)
     = $0.000950 ≈ 不到台幣一毛錢

這也是為什麼說 API 適合大量自動化:單次請求幾乎是微不足道的費用,但如果你一天送一百萬次就不同了——選對模型、用好 Caching 和 Batch,才是成本控制的關鍵。

觀念三:三個模型,各有定位

截至 2026 年 7 月,Claude 4 系列有三個主要模型:

本課所有範例用 claude-haiku-4-5——它最便宜,測試時不會燒錢,等你確認程式能跑再換成 Sonnet。模型選擇的完整策略是第 2 課的主題。

三個模型的能力邊界值得記住:Haiku 適合短文本分類、簡單問答、格式轉換等機械性任務;Sonnet 是你的日常主力,處理中等複雜度的推理和生成;Opus 則留給真正需要深度思考的場景——例如法律文件解析、複雜的多步驟規劃,或要求嚴格邏輯正確性的場合。用 Opus 跑簡單任務是最常見的浪費,用 Haiku 跑複雜推理則會得到不可靠的答案。

Batch API 對所有模型打五折;Prompt Caching 快取讀取再打一折(省 90%)。這兩個省錢技巧在第 7 課完整介紹。

手把手實戰

ANTHROPIC_API_KEY=sk-ant-api03-你的實際金鑰

.env

git status
# .env 應該不出現在 Changes 或 Untracked files 裡

pip install anthropic
# 或用 uv
uv add anthropic

python -c "import anthropic; print(anthropic.__version__)"
# 2026 年 7 月現況約 0.116.x,新專案直接裝最新版即可

npm install @anthropic-ai/sdk
# 或
pnpm add @anthropic-ai/sdk

node -e "const a = require('@anthropic-ai/sdk'); console.log(a.default?.VERSION ?? 'ok')"

pip install python-dotenv

npm install dotenv

import os
from dotenv import load_dotenv
import anthropic

# 從 .env 讀取金鑰
load_dotenv()

# 初始化 client,若環境變數 ANTHROPIC_API_KEY 存在會自動讀取
client = anthropic.Anthropic()

# 呼叫 messages API
message = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "用一句話解釋什麼是 API?"
        }
    ]
)

# 印出回應
print(message.content[0].text)
print(f"\n--- 用量統計 ---")
print(f"輸入 token: {message.usage.input_tokens}")
print(f"輸出 token: {message.usage.output_tokens}")
print(f"停止原因:  {message.stop_reason}")

python first_call.py

API(應用程式介面)是一套規則,讓不同的軟體系統之間能夠溝通與交換資料。

--- 用量統計 ---
輸入 token: 18
輸出 token: 32
停止原因:  end_turn

import Anthropic from "@anthropic-ai/sdk";
import "dotenv/config";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await client.messages.create({
  model: "claude-haiku-4-5",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: "用一句話解釋什麼是 API?",
    },
  ],
});

console.log(message.content[0].text);
console.log("\n--- 用量統計 ---");
console.log("輸入 token:", message.usage.input_tokens);
console.log("輸出 token:", message.usage.output_tokens);
console.log("停止原因: ", message.stop_reason);

node first_call.mjs

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "API(應用程式介面)是..."
    }
  ],
  "model": "claude-haiku-4-5-20251001",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 18,
    "output_tokens": 32
  }
}

常見坑

坑 1:401 認證錯誤——invalid x-api-key

anthropic.AuthenticationError: Error code: 401 - {'type': 'error', 'error': {'type': 'authentication_error', 'message': 'invalid x-api-key'}}

這個錯誤有三個常見原因,依序排查:

1. .env 檔案路徑不對——執行 python first_call.py 時,工作目錄必須和 .env 在同一層,或用 load_dotenv(dotenv_path="絕對路徑") 指定
2. 金鑰複製時不小心多了空格——打開 .env,確認 = 後面沒有前後空格,金鑰本身不要加引號
3. 帳戶餘額歸零——到 Console 的 Billing 頁面確認還有剩餘額度,帳單欠費時 Anthropic 會讓金鑰繼續存在但請求全部回 401

坑 2:429 頻率限制——rate_limit_error

anthropic.RateLimitError: Error code: 429 - {'type': 'error', 'error': {'type': 'rate_limit_error', 'message': 'Number of requests has exceeded your per-minute rate limit'}}

新帳號預設在 Tier 1,限制相對保守(約 50 RPM)。短時間內連續送大量請求就會觸發。解法:

import time
import anthropic

client = anthropic.Anthropic()

def safe_create(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.messages.create(
                model="claude-haiku-4-5",
                max_tokens=1024,
                messages=messages
            )
        except anthropic.RateLimitError as e:
            wait = 2 ** attempt  # 指數退避:1s, 2s, 4s
            print(f"Rate limit 了,等 {wait} 秒後重試...")
            time.sleep(wait)
    raise Exception("重試三次都失敗")

長期解法是到 Console 的 Settings → Limits 確認你的 Tier,然後增加帳戶充值金額(Tier 升級是自動的,累積消費越多限制越寬鬆)。

坑 3:.env 不小心進了 git,金鑰外洩

如果你發現 GitHub repo 的檔案列表看得到 .env,處理順序必須是:

1. 先換鑰匙:立刻到 Console 的 API Keys 把那把金鑰 Revoke(作廢)、再建一把新的——因為 git 歷史裡的舊金鑰就算刪掉檔案也還在,機器人能翻到
2. 再清理 git:把 .env 加進 .gitignore,執行 git rm --cached .env,然後 commit 並 push

echo ".env" >> .gitignore
git rm --cached .env
git commit -m "remove .env from tracking"
git push

3. 如果 repo 是公開的,舊金鑰幾乎必定已被掃描到,一定要 Revoke。私有 repo 也要換——安全習慣比僥倖心理重要。

坑 4:content[0].text 拋出 IndexError 或 AttributeError

AttributeError: 'ToolUseBlock' object has no attribute 'text'

這個錯誤在你開始用 Tool Use(第 5 課主題)之後會出現:content 陣列不一定只有 TextBlock,也可能有 ToolUseBlock。安全的取文字方式:

# 只取第一個 TextBlock
text_blocks = [b for b in message.content if b.type == "text"]
if text_blocks:
    print(text_blocks[0].text)

在只做純文字對話的場景(本課內容),content[0].text 是安全的;一旦加入 Tool Use 就要改成上面的寫法。

作業

1. 用你自己的 API Key 跑通本課的 Python 或 JS 範例,印出回應和用量統計
2. 把模型換成 claude-sonnet-4-6,送同一個問題,比較回應品質和 token 數的差異
3. 故意把 max_tokens 設成 5,觀察 stop_reason 是不是變成 max_tokens,以及回應被截斷的效果
4. 在 Console 的 Usage 頁面看到剛才的請求紀錄,確認你理解帳單的計算方式

下一課預告

你現在已經能讓程式跟 Claude 說話了。但三個模型的差異遠不只是價格——Opus 在複雜推理上的表現可能是 Haiku 的數倍,選錯模型不是「只是貴一點」,而是「功能根本不夠用」或「白白燒了十倍成本」。**第 2 課「模型與計價:選對模型省十倍」**會帶你做實際的 benchmark 測試,用數據建立你自己的模型選擇框架,讓每一分錢花在刀口上。