對話平台 Credits 額度 API
用 API 分發對話平台 Credits 額度、調整預算及切換「需要額度」,分清對話平台 ID、額度 ID 與停用額度的影響。
整合系統可以為 Web Chat、LINE 等對話平台分配 Credits 消費上限,並切換該平台是否必須有額度才能使用 AI。這是對話平台的預算管控;後台操作與額度用完時的體驗,請見使用者手冊對話平台 Credits 額度管理。
例如,網站服務商為不同活動建立各自的 Web Chat,希望由自己的管理系統分發活動預算。系統先查出該活動的對話平台 ID,再建立額度並讀回檢查;活動取消時,管理者可以停用額度,或解除「需要額度」,兩者的效果不同。
呼叫前先確認
這組 API 適用於 Credits 計費的組織;呼叫者需要組織的 Credit 管理權限,讀取也需要此權限。
使用 API 共通規範 的 API Key 認證方式。金鑰所屬成員必須有上述權限。
inboxId是對話平台 ID,不是 Agent ID。同一個 Agent 的不同入口可能是不同對話平台;MaiGPT 的對話平台不適用本頁額度管控。quotaId是建立額度後回傳的id,不是對話平台 ID。
端點怎麼選
下列路徑都加在平台網址之後;SaaS 例如 https://api.maiagent.ai。
查詢組織的對話平台與額度摘要
GET /api/v1/organizations/{organizationId}/credit-quota-inboxes/
列出某個對話平台的額度紀錄
GET /api/v1/inboxes/{inboxId}/credit-quotas/
分發一筆額度
POST /api/v1/inboxes/{inboxId}/credit-quotas/
讀取單筆額度
GET /api/v1/inboxes/{inboxId}/credit-quotas/{quotaId}/
修改啟用中的額度
PATCH /api/v1/inboxes/{inboxId}/credit-quotas/{quotaId}/
停用一筆額度
DELETE /api/v1/inboxes/{inboxId}/credit-quotas/{quotaId}/
切換「需要額度」
PATCH /api/v1/organizations/{organizationId}/credit-quota-inboxes/{inboxId}/credit-quota-required/
組織的對話平台列表不包含 MaiGPT。可用 search 搜尋對話平台名稱、Agent 名稱或對話平台 ID;請依回應的分頁資訊取完所需資料。
分發額度
向對話平台的 credit-quotas/ 路徑送出 POST。以下是請求內容範例;請將生效時間換成您的實際活動時間:
quotaLimit
必填,額度上限,不可小於 0;最多 18 位數,其中小數最多 6 位
validFrom
必填,生效時間;範例使用含時區的 ISO 8601 時間
validUntil
選填,到期時間;省略或 null 表示不設定到期時間。若填寫,須晚於生效時間;組織有有效入帳額度時,也不能晚於其中最晚的到期日
resetPeriod
選填,none、daily、weekly、monthly;預設 none。週期行為見設定重置週期
note
選填,備註;預設空字串
建立成功回 201 與額度資料,請保存回傳的額度 id,再用單筆額度的 GET 讀回確認。建立額度也會自動將該對話平台的「需要額度」設為開啟。
同一個對話平台不能同時有兩筆啟用中的額度。已有啟用中的額度時,請用 PATCH 修改,或先停用舊額度再分發;不要反覆重送建立請求。
調整既有額度
對單筆額度路徑送出 PATCH,只帶要修改的欄位,例如:
可調整 quotaLimit、validUntil、note 與 resetPeriod。不能透過這個端點改生效時間;已停用的額度也不能再修改。降低額度時,上限不可低於已消耗額度。
停用額度與解除限制不同
DELETE 單筆額度成功回 204,表示停用額度,不會刪除額度紀錄,也不會同時關閉「需要額度」。若平台仍需要額度,停用後沒有有效額度可用,AI 回覆就會受到限制。
若要解除對話平台額度限制,請對上述 credit-quota-required/ 路徑送出:
這會關閉「需要額度」,並一併停用既有啟用中的額度。反過來,送出 true 只會開啟「需要額度」,不會自動分發新額度。切換成功回 200 與更新後的平台額度摘要;請檢查 creditQuotaRequired,再查單筆額度確認狀態。
最後更新於
這有幫助嗎?