快速上手
開始呼叫 MaiAgent 平台 API：基本網址、取得 API 金鑰的兩種方式（成員自建、管理者代發）、金鑰的權限範圍，以及第一個請求範例。
本頁帶您完成呼叫平台 API 前的準備：確認網址、取得 API 金鑰、送出第一個請求。各端點的欄位與完整範例以 API 文件 為準；認證、速率限制、錯誤格式等跨端點規則見 API 共通規範。
API 串接文件與範例程式碼
基本 API 網址
地端與私有雲部署請換成貴公司的平台網域。新的整合請一律使用 /api/v1/ 前綴，說明見 網址與版本前綴。
取得 API 金鑰
API 金鑰有兩種取得方式，兩種金鑰的呼叫方式相同。
成員自建
組織內的有效成員都可以在後台右上角頭像 → 帳號 → API 金鑰 為自己建立金鑰，不需要額外權限。金鑰建立在目前切換到的組織，完整金鑰只在建立當下顯示一次。操作步驟見使用者手冊的 成員自行建立金鑰。
管理者代發
具備「API Key 管理權限」的管理者，可以在 組織設定 → API Key 管理 替指定成員簽發金鑰，並設定到期時間、每分鐘請求數（RPM）、停用或撤銷。操作步驟見使用者手冊的 建立 API Key。
金鑰的權限範圍
金鑰綁定一位成員：呼叫時的組織與權限，就是這位成員在該組織的身分與角色權限，請求不需要另外帶組織 ID，也沒有依端點細分的權限範圍。成員被停用或移出組織後，金鑰立即失效。完整規則與整合用金鑰的建議見 API 共通規範：認證。
送出第一個請求
在 Authorization 標頭帶入金鑰，格式是 Api-Key <金鑰>（不是 Bearer）：
以列出 Agent 為例：
回應為分頁格式（count、next、previous、results），欄位一律是 camelCase，說明見 分頁 與 欄位格式。收到 401 時，請確認金鑰狀態與標頭格式，見 錯誤回應。
下一步
端點與認證細節：API 文件：API 認證方式
跨端點規則：API 共通規範
建立對話、送出訊息與附件：建立對話與訊息
取得 Agent 回覆（串流或同步）：對話與訊息回覆（串流／同步）
管理知識庫檔案與檢索：使用知識庫—上傳、搜尋與管理
把對話事件推送到您的系統：Webhook
最後更新於
這有幫助嗎？