API 共通規範

呼叫 MaiAgent 平台 API 的共通規則摘要：網址與版本前綴、API Key 認證、速率限制、錯誤回應、分頁、欄位格式與上傳大小上限；正本在 API 文件

API 跨端點的共通規則以 API 文件的 API 共通規範 為正本，開發者串接時請以該頁為準。本頁只留各節的一兩句摘要，每節都連到 API 文件的同名段落。

各端點的欄位與範例見 API 文件站；建立與管理 API Key 的畫面操作見使用者手冊 API Key 管理。

網址與版本前綴

SaaS 的 API 網址是 https://api.maiagent.ai/api/v1/，地端與私有雲換成貴公司的平台網域；新的整合請一律使用 /api/v1/。詳見 API 共通規範：網址與版本前綴。

認證

伺服器對伺服器的呼叫在 Authorization 標頭帶 Api-Key <金鑰>；金鑰綁定一位成員，權限等於該成員的角色。失效條件、認證失敗的回應與整合用金鑰的建議，見 API 共通規範：認證。

每位成員可以同時持有多把有效金鑰，沒有數量上限（見使用者手冊 API Key 管理）。金鑰也可以用 API 簽發：管理者代發用 POST /api/v1/organizations/{organizationPk}/api-keys/（需要「API Key 管理權限」，可設定名稱、到期時間與 RPM），成員自建用 POST /api/v1/organizations/{organizationPk}/my-api-keys/；撤銷用對應的 DELETE。完整金鑰只在建立的回應中出現一次。欄位見 API 文件組織和成員。

速率限制

平台 API 沒有全域的預設上限，主要的限制是每把 API Key 的 RPM 與 AI Gateway 的 TPM；超過上限回 429 並帶 Retry-After。完整的限流範圍見 API 共通規範：速率限制。

錯誤回應

請依 HTTP 狀態碼與 code 判斷錯誤，不要比對 detail 文字。錯誤內容的形狀、各狀態碼的處理建議與 402 的情況，見 API 共通規範：錯誤回應。

分頁

多數列表用 page／page_size 頁碼分頁（預設 20、上限 100），以 next 取下一頁；對話與訊息列表用游標分頁。詳見 API 共通規範：分頁。

欄位格式

回應的 key 一律是 camelCase，時間欄位多為毫秒時間戳記字串。詳見 API 共通規範：欄位格式。

上傳大小上限

上傳上限以 GET /api/v1/allowed-file-specs/ 的回應為準，各用途的現值見 API 共通規範：上傳大小上限。Presigned 上傳流程見 Presigned 檔案上傳模式。

請求內容的編碼

請求與回應的 JSON 一律是 UTF-8。角色指令（instructions）、訊息內容等欄位可以直接放中文與其他 Unicode 字元，不需要轉成 ASCII 或跳脫；請在請求帶 Content-Type: application/json，並確認您的 HTTP 用戶端以 UTF-8 編碼送出。回應的 JSON 也以 UTF-8 原文回傳，不會轉成 \uXXXX。更新後用對應的 GET 讀回即可確認儲存的內容；後台畫面顯示的是同一份資料。

請求大小與 413

• 平台 API 本身不會回 413。JSON 請求本體超過 Django 的預設上限（2.5 MB）時回 400；這個上限只算 JSON 與表單欄位，不算 multipart 的檔案本體。

• 檔案大小由 GET /api/v1/allowed-file-specs/ 的上限決定，超過時在取得上傳網址或登記檔案的步驟回 400，見上傳大小上限。

• 收到 413 代表整個請求被平台前方的代理層（CDN／負載平衡）擋下，通常是把檔案以 Base64 放進 JSON，或直接以 multipart 送大檔。請改用 Presigned 檔案上傳模式：檔案直接傳到儲存空間，API 請求只帶檔案的 key。

常見問題

金鑰一直回 401、能不能限制金鑰的呼叫範圍、/api/ 與 /api/v1/ 的差別，見 API 共通規範：常見問題。