本文涵蓋與不涵蓋的內容
本指南涵蓋在 Claude Console 建立 Anthropic API Key、送出第一次 Messages API 請求、查看用量,以及處理常見錯誤。
本指南不涵蓋消費級 Claude 方案。使用消費級方案登入 Claude 不會取得 API Key。API 用量透過 Console 另行計費。方案詳情見 Claude 價格頁面。
前置條件
- 一個可以收信的電子郵件信箱,以及用於支付 API 用量的付款方式(見第 2 步)
- 已安裝
curl的終端機 - 用於保存 Key 的安全位置,例如密碼管理器或金鑰管理服務
- 若屬於某個組織,需有建立 Key 的權限。若 “Create key” 按鈕無法使用,可能是您的角色沒有此權限,請洽組織管理員。
第 1 步:建立 Console 帳號
前往 platform.claude.com,註冊或登入。API 概覽將 Claude Console 帳號列為使用 API 的第一項前置條件。
第 2 步:設定計費並了解隨用量計費
API 請求依 token 計費,費率因模型而異。價格頁面以每百萬 token(MTok)的美元價格列出各模型費率。本指南不重複這些數字,因為費率會變動;規劃專案前請先查看該頁面。
在 Console 開啟 Billing 頁面購買額度或管理付款方式。標準帳號可使用主要信用卡付款。
每個用量層級都有每月消費上限。您可以在 Spend limits 頁面設定低於上限的個人限額。速率限制文件說明消費上限與請求速率限制的差異。
第 3 步:建立 API Key,並只複製一次
- 在 Console 開啟 API keys 頁面。
- 點選 Create key,命名、選擇有效期限,並將 Linked account 設為您本人或某個服務帳號。也可以選擇工作區(workspace)。
- 立即複製 Key。Console 只會在建立時顯示完整 Key,它以
sk-ant-開頭。若遺失,將無法再次查看,只能重新建立。
個人 Key 適用於您自己的開發;服務帳號 Key 適用於共享用途,例如 CI 流程或正式環境服務。請將 Key 保存在金鑰管理服務中,不要存入專案檔案。
第 4 步:送出第一次 Messages API 請求
只在 shell 工作階段中設定 Key,不要寫入腳本或檔案。接著執行以下請求:
# Set ANTHROPIC_API_KEY in this shell first, for example from your secrets manager.
# Never paste the key itself into a file, script or chat.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": "Say hello in one sentence."
}
]
}'
範例中的模型 ID 來自官方入門範例。模型 ID 會變動,依賴前請以 Console 或官方模型文件列出的 ID 取代。成功的回應是 JSON,其中 id 以 msg_ 開頭,並包含帶文字的 content 陣列。
第 5 步:在 Console 查看用量
Claude Console 提供用量追蹤。完成測試請求後,開啟用量檢視,確認請求出現在預期的工作區下。也請檢查 Spend limits 與 Billing 頁面。用量檢視的確切選單位置在已查核資料中為 UNKNOWN,請在 Console 導覽中尋找用量相關入口。
Key 安全
- 絕不提交 Key。 不要把它放進 Git、工單、聊天、截圖或原始碼中。從環境變數或金鑰管理服務載入。
- 外洩時輪替。 建立新 Key、更新應用程式,然後在 API keys 頁面刪除舊 Key。
- 每個專案或服務使用一個 Key。 獨立的 Key 讓您可以輪替其中一個而不影響其他。共享工作負載應使用服務帳號 Key。
- 不要在瀏覽器端使用 Key。 對於限制直接瀏覽器呼叫的組織,瀏覽器請求可能回傳 401。請從您自己的後端送出 API 請求。
疑難排解
Claude API 錯誤參考是錯誤類型的權威來源。請先檢查回應中的狀態碼與錯誤類型。
| 狀態碼 | 錯誤類型 | 檢查重點 |
|---|---|---|
| 401 | authentication_error | Key 可能格式錯誤、已被撤銷或已過期。執行 echo "${#ANTHROPIC_API_KEY}" 僅顯示長度;0 表示此 shell 中變數為空。如有需要請重新建立 Key。 |
| 402 | billing_error | 在 Billing 頁面檢查付款資訊。 |
| 403 | permission_error | Key 無權存取該資源。檢查組織權限與工作區設定。若 Key 未限定於某工作區,驗證文件說明了 anthropic-workspace-id 標頭。地區作為原因:已查核資料中為 UNKNOWN。 認證文件 |
| 404 | not_found_error | 檢查端點路徑與資源 ID。 |
| 429 | rate_limit_error | 可能是速率限制,也可能是每月消費上限。使用指數退避等待後重試;若存在 retry-after 標頭則遵循它。消費上限造成的 429 不含 retry-after,且會持續失敗直到存取恢復,請查看 Spend limits 頁面。 |
| 500 | api_error | 使用指數退避重試;若持續發生,請附上請求 ID 聯絡支援。 |
| 504 | timeout_error | 對於較長的 Messages API 請求,請使用串流。 |
| 529 | overloaded_error | API 因整體流量暫時過載。請稍後以退避方式重試。 |
官方 SDK 會對部分暫時性失敗自動重試,預設兩次。速率限制文件說明限制如何隨時間執行。
已暫停的消費級 Claude 帳號是另一種情況
消費級 Claude 帳號被暫停或受限,與 API Key 分開處理。建立 API Key 不會改變消費級帳號的狀態。請遵循官方 Claude 說明中心關於安全保障警告與申訴的文章及通知中的指示。Cue 無法恢復或繞過供應商帳號,也無法承諾任何審查結果。關於此情況的 Cue 指南,請見 Cue 的 Claude 帳號暫停指南。
一款用於日常工作的桌面 AI 助手。 使用 Cue 整理筆記、文件與任務,可選 Claude 與 GPT 模型。請在您的 Cue 帳號中查看可用模型與額度,並閱讀 Cue 條款。Cue 無法核發 Anthropic API Key,也無法改變 Anthropic 對帳號、計費或 Key 的決定。
正在處理暫停的 Claude 帳號?請參閱 Cue 的 Claude 帳號暫停指南。