如何把 Claude API 整合進你的 App

要整合 Claude API，請先在 Anthropic 的 Claude Console 建立 API 金鑰，把它存成伺服器端機密（通常是 ANTHROPIC_API_KEY），然後使用 Anthropic 官方 SDK 之一，從你自己伺服器上的路由呼叫 Messages API。每個請求都要指定一個 model、設定 max_tokens（你願意接受的最長回覆），並以 messages 傳送對話內容，而你的指示則放在獨立的 system 系統提示中。請設定支出上限、長回覆使用串流，並以重試機制處理速率限制（429）與過載（529）錯誤。

本指南涵蓋設定、安全的請求流程、給 AI 建構工具的提示詞，以及需要預先規劃的錯誤。Anthropic 的細節來自其截至 2026 年 9 月的官方文件。關於權杖與定價的一般運作方式，請參閱如何使用 LLM API。

你可以用它做什麼

• 聊天助理與說明小工具（如何建立 AI 聊天機器人 App）
• 摘要、改寫與草擬回覆
• 從文件、電子郵件與表單中擷取欄位
• 根據你自己的內容回答問題
• 透過工具呼叫（tool use），讓 Agent 呼叫你 App 中的函式

更多想法請參閱如何為你的 App 加入 AI 功能。

Messages API 簡介

根據 Anthropic 的 API 參考文件，請求是對 https://api.anthropic.com/v1/messages 發出的 POST，包含：

API 是無狀態的：若要延續對話，每次請求都必須重新傳送先前的回合。這也是為什麼長對話每則訊息的成本會更高。

Anthropic 為 Python、TypeScript、C#、Go、Java、PHP 與 Ruby 提供官方 SDK。它們會設定標頭、解析回應，並支援串流。除非有特別理由，請優先使用 SDK，而不是直接發送原始 HTTP 請求。

選擇模型

Anthropic 提供數款 Claude 模型，在能力、速度與價格之間各有取捨，而且產品線會變動。請選擇能把任務做好的最小模型，用真實範例測試，並把模型 ID 放在設定檔中，讓你無需修改程式碼即可切換。目前可用的選項與費率，請查看 Anthropic 的模型與定價頁面。

設定你的帳號

1. 登入 Claude Console（platform.claude.com）並加入付款方式。
2. 建立 API 金鑰。 每個環境（測試與正式）各保留一組金鑰，讓你撤銷其中一組時，不會影響另一組。
3. 設定支出上限。 Anthropic 的錯誤頁面指出，當用量達到你設定的支出上限時，API 會回傳 400 錯誤，因此你的 App 應該在這種情況下顯示清楚的訊息。
4. 查看速率限制。 在 Console 中檢視你帳號的速率限制；限制是以組織為單位計算。

請求流程

1. 用戶在你的 App 中操作：送出訊息、點擊「摘要」。
2. 瀏覽器呼叫的是你的伺服器路由，而不是直接呼叫 Anthropic。
3. 你的伺服器確認用戶已登入且有權使用此功能，並套用每位用戶的限制。
4. 伺服器建立請求：包含你的規則的系統提示、用戶的輸入，以及任務所需、來自你資料庫的資料。
5. 伺服器使用環境變數中的金鑰，並設定合理的 max_tokens，呼叫 Messages API。
6. 伺服器把回覆串流給瀏覽器，並記錄回應中的權杖用量。

選項與取捨

給 AI 建構工具的提示詞

第一個功能：

新增一個「詢問此文件」面板。它會呼叫伺服器路由 POST /api/ask，該路由會檢查用戶是否已登入且擁有此文件，接著使用官方 Anthropic SDK 與機密 ANTHROPIC_API_KEY 呼叫 Claude Messages API。請從機密 CLAUDE_MODEL 讀取模型 ID。系統提示為：「只根據提供的文件回答。如果文件中沒有答案，請直說。」傳送文件內容與問題，將 max_tokens 設為 800，把回答串流到頁面上，並且絕對不要把金鑰暴露給瀏覽器。

防護與錯誤處理：

將每位用戶限制為每小時 20 個問題，並記錄在資料庫中。每次回應都要記錄輸入與輸出權杖數，並附上用戶 ID 與請求 ID。遇到 429 或 529 錯誤時，以指數退避最多重試 3 次，並遵守 retry-after 標頭；之後顯示「助理目前忙碌中，請稍後再試。」如果 API 回報支出上限錯誤，則顯示「AI 功能已暫停」並通知管理員。

需要預先規劃的錯誤

以下是根據 Anthropic 錯誤文件，你的 App 實際上會遇到的錯誤：

Anthropic 文件指出，官方 SDK 預設會以指數退避，自動重試暫時性失敗（連線錯誤、速率限制與 5xx 錯誤）兩次，並且你可以調整此設定。每個回應都會帶有 request-id 標頭；請記錄下來，方便支援團隊追蹤問題。

常見錯誤

• 從瀏覽器呼叫 API。 你的金鑰會被公開。請一律經過你的伺服器。參閱如何保護 API 金鑰安全。
• 忘記 max_tokens 是上限，而不是目標值。 請設定為該功能所需的長度；太低會截斷回答，太高則可能產生冗長且昂貴的回覆。
• 把規則放在用戶訊息中。 固定的指示應該放在 system 系統提示中；權限則應該由你的程式碼控制。
• 永遠傳送整個聊天記錄。 隨著對話變長，請修剪或摘要舊的回合。
• 沒有支出上限或每位用戶的限制。
• 寫死模型 ID。 模型會被更新與淘汰。
• 忽略停止原因（stop reason）。 如果回覆是因為達到 max_tokens 而停止，請告知用戶或提高上限。

檢查清單

• 已在 Claude Console 建立 API 金鑰，並存成伺服器端機密
• 測試與正式環境使用不同的金鑰
• 已設定支出上限；達到上限時顯示清楚的訊息
• 所有請求都經過你的伺服器，並進行權限檢查
• 規則放在系統提示中；模型 ID 可以設定
• 每個功能都設定了 max_tokens；較長的回覆使用串流
• 你的 App 中有每位用戶的速率限制
• 已以退避方式處理 429 與 529；已記錄請求 ID
• 有友善的錯誤狀態，不會讓頁面損壞
• 已用空白、超長與惡意的輸入測試過

在 Mythex 中使用 Claude API

在你使用 Mythex 建構的 App 中，Claude 功能使用你自己的 Anthropic 金鑰，並由你的 Anthropic 帳號計費，而不是由 Mythex 建構點數計費。這與撰寫你程式碼的 Mythex Agent 是分開的。請透過 /secrets、專案設定，或聊天中的機密卡片，把 ANTHROPIC_API_KEY 加入為專案機密，然後使用類似上述的提示詞描述功能。如果是已上線的 App，變更機密後請重新發布。入門提示詞請參閱使用你自己的 API 金鑰加入 AI 功能。如果你正在比較不同的供應商，如何整合 OpenAI API 介紹了 OpenAI 的相同內容。

常見問題