點樣將 Claude API 整合入你嘅 App

要整合 Claude API，先喺 Anthropic 嘅 Claude Console 建立一條 API 金鑰，然後將佢儲存為伺服器端機密（通常係 ANTHROPIC_API_KEY），再喺你自己嘅伺服器路由，用 Anthropic 官方 SDK 之一去呼叫 Messages API。每個請求都要指定一個 model，設定 max_tokens（你願意接受嘅最長回覆），並且將對話以 messages 傳送，而你嘅指示就放喺獨立嘅 system 提示入面。設定消費上限，長回覆用串流，並且用重試處理速率限制（429）同超負荷（529）錯誤。

本指南涵蓋設定、安全嘅請求流程、畀 AI builder 用嘅提示，以及要預防嘅錯誤。Anthropic 嘅資料取自佢哋截至 2026 年 9 月嘅文件。要了解 token 同定價嘅一般概念，先睇點樣使用 LLM API。

你可以用佢整咩

• 聊天助理同幫助小工具（點樣建立 AI 聊天機械人 App）
• 摘要、改寫同草擬回覆
• 由文件、電郵同表格抽取欄位
• 根據你自己嘅內容回答問題
• 透過 tool use 呼叫你 App 功能嘅 Agent

更多idea可以睇點樣為你嘅 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. 登入 platform.claude.com 嘅 Claude Console，並且加入帳單。
2. 建立 API 金鑰。 測試同正式環境各用一條金鑰，咁樣撤銷其中一條都唔會影響另一條。
3. 設定消費上限。 Anthropic 嘅錯誤頁面提到，當用量達到你設定嘅上限時，API 會返回 400 錯誤，所以你嘅 App 要喺呢種情況顯示清楚嘅訊息。
4. 檢查速率限制，喺 Console 睇你帳戶嘅限制；佢哋係以組織為單位計算。

請求流程

1. 用戶喺你嘅 App 入面操作：傳送訊息，撳「摘要」。
2. 瀏覽器呼叫你自己嘅伺服器路由，而唔係直接呼叫 Anthropic。
3. 你嘅伺服器檢查用戶已登入，並且有權使用該功能，同時套用每位用戶嘅限制。
4. 組裝請求：一個包含你規則嘅系統提示、用戶嘅輸入，以及任務需要從你資料庫攞嘅任何資料。
5. 用環境入面嘅金鑰，並且設定一個合理嘅 max_tokens，去呼叫 Messages API。
6. 將回覆串流回瀏覽器，並且由回應入面記錄 token 用量。

選項同取捨

畀你嘅 AI builder 嘅提示

第一個功能：

加入一個「問呢份文件」面板。佢會呼叫一個伺服器路由 POST /api/ask，檢查用戶已登入並擁有該文件，然後用官方 Anthropic SDK 同機密 ANTHROPIC_API_KEY 呼叫 Claude Messages API。由機密 CLAUDE_MODEL 讀取模型 ID。系統提示：「只根據提供嘅文件作答。如果答案唔喺文件入面，就直接講明。」傳送文件文字同問題，將 max_tokens 設為 800，將答案串流到頁面，並且絕對唔好將金鑰暴露畀瀏覽器。

防護同錯誤：

限制每位用戶每個鐘頭最多問 20 條問題，記錄喺資料庫入面。每個回應都記錄輸入同輸出 token，連同用戶 ID 同請求 ID。遇到 429 或 529 錯誤時，用指數退避最多重試 3 次，並且遵從 retry-after 標頭；之後顯示「助理而家好忙，遲啲再試」。如果 API 報告消費上限錯誤，就顯示「AI 功能已暫停」，並且通知管理員。

要預防嘅錯誤

根據 Anthropic 嘅錯誤文件，以下係你嘅 App 實際會遇到嘅錯誤：

Anthropic 嘅文件表示，官方 SDK 預設會自動重試暫時性失敗（連線錯誤、速率限制同 5xx 錯誤）兩次，並且採用指數退避，你可以設定。每個回應都會帶有 request-id 標頭；記錄低佢，咁樣支援人員就可以追查問題。

常見錯誤

• 喺瀏覽器呼叫 API。 你嘅金鑰就會公開。永遠經過你嘅伺服器。睇點樣保護 API 金鑰。
• 唔記得 max_tokens 係上限，唔係目標。 設定為該功能所需嘅數值；太低會截斷答案，太高就有機會出現冗長又昂貴嘅回覆。
• 將規則放喺用戶訊息入面。 穩定嘅指示應該放喺 system 提示；權限就應該放喺你嘅程式碼入面。
• 永遠傳送整段聊天。 對話越長，就要修剪或者摘要舊嘅回合。
• 冇消費上限或者冇每位用戶限制。
• 寫死模型 ID。 模型會更新同停用。
• 忽略停止原因。 如果回覆因為達到 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 嘅相同內容。

常見問題