> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/api-integration/endpoint-behaviors/inbox-credit-quota-api.md).

# 對話平台 Credits 額度 API

用 API 分發對話平台 Credits 額度、調整預算及切換「需要額度」，分清對話平台 ID、額度 ID 與停用額度的影響。

整合系統可以為 Web Chat、LINE 等對話平台分配 Credits 消費上限，並切換該平台是否必須有額度才能使用 AI。這是對話平台的預算管控；後台操作與額度用完時的體驗，請見使用者手冊[對話平台 Credits 額度管理](https://docs.maiagent.ai/others/credits/inbox-credit-quota)。

例如，網站服務商為不同活動建立各自的 Web Chat，希望由自己的管理系統分發活動預算。系統先查出該活動的對話平台 ID，再建立額度並讀回檢查；活動取消時，管理者可以停用額度，或解除「需要額度」，兩者的效果不同。

## 呼叫前先確認 <a href="#prerequisites" id="prerequisites"></a>

* 這組 API 適用於 Credits 計費的組織；呼叫者需要組織的 **Credit 管理權限**，讀取也需要此權限。
* 使用 [API 共通規範](https://docs.maiagent.ai/tech/api-integration/api-conventions.md#authentication) 的 API Key 認證方式。金鑰所屬成員必須有上述權限。
* `inboxId` 是**對話平台 ID**，不是 Agent ID。同一個 Agent 的不同入口可能是不同對話平台；MaiGPT 的對話平台不適用本頁額度管控。
* `quotaId` 是建立額度後回傳的 `id`，不是對話平台 ID。

## 端點怎麼選 <a href="#endpoints" id="endpoints"></a>

下列路徑都加在平台網址之後；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；請依回應的分頁資訊取完所需資料。

{% hint style="info" %}
JSON 欄位使用 camelCase。額度清單與詳情回傳 `quotaLimit`、`consumedAmount`、`remaining`、`isActive` 等欄位；不要把已用額度當成組織錢包餘額。
{% endhint %}

## 分發額度 <a href="#allocate-quota" id="allocate-quota"></a>

向對話平台的 `credit-quotas/` 路徑送出 `POST`。以下是請求內容範例；請將生效時間換成您的實際活動時間：

```json
{
  "quotaLimit": "500.000000",
  "validFrom": "2026-11-01T00:00:00+08:00",
  "validUntil": null,
  "resetPeriod": "none",
  "note": "活動客服預算"
}
```

| 欄位            | 建立時的要求                                                                                                                                       |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `quotaLimit`  | 必填，額度上限，不可小於 0；最多 18 位數，其中小數最多 6 位                                                                                                           |
| `validFrom`   | 必填，生效時間；範例使用含時區的 ISO 8601 時間                                                                                                                 |
| `validUntil`  | 選填，到期時間；省略或 `null` 表示不設定到期時間。若填寫，須晚於生效時間；組織有有效入帳額度時，也不能晚於其中最晚的到期日                                                                            |
| `resetPeriod` | 選填，`none`、`daily`、`weekly`、`monthly`；預設 `none`。週期行為見[設定重置週期](https://docs.maiagent.ai/others/credits/member-credit-quota#quota-reset-period) |
| `note`        | 選填，備註；預設空字串                                                                                                                                  |

建立成功回 `201` 與額度資料，請保存回傳的額度 `id`，再用單筆額度的 `GET` 讀回確認。建立額度也會自動將該對話平台的「需要額度」設為開啟。

同一個對話平台不能同時有兩筆啟用中的額度。已有啟用中的額度時，請用 `PATCH` 修改，或先停用舊額度再分發；不要反覆重送建立請求。

## 調整既有額度 <a href="#update-quota" id="update-quota"></a>

對單筆額度路徑送出 `PATCH`，只帶要修改的欄位，例如：

```json
{
  "quotaLimit": "800.000000",
  "note": "活動延長，調高預算"
}
```

可調整 `quotaLimit`、`validUntil`、`note` 與 `resetPeriod`。不能透過這個端點改生效時間；已停用的額度也不能再修改。降低額度時，上限不可低於已消耗額度。

## 停用額度與解除限制不同 <a href="#deactivate-vs-remove-requirement" id="deactivate-vs-remove-requirement"></a>

`DELETE` 單筆額度成功回 `204`，表示**停用額度**，不會刪除額度紀錄，也不會同時關閉「需要額度」。若平台仍需要額度，停用後沒有有效額度可用，AI 回覆就會受到限制。

若要**解除對話平台額度限制**，請對上述 `credit-quota-required/` 路徑送出：

```json
{
  "creditQuotaRequired": false
}
```

這會關閉「需要額度」，並一併停用既有啟用中的額度。反過來，送出 `true` 只會開啟「需要額度」，不會自動分發新額度。切換成功回 `200` 與更新後的平台額度摘要；請檢查 `creditQuotaRequired`，再查單筆額度確認狀態。

{% hint style="warning" %}
解除對話平台額度限制不會補充組織錢包，也不會解除其他適用的額度限制。完整管控層次見使用者手冊[三層額度如何搭配](https://docs.maiagent.ai/others/credits/inbox-credit-quota#quota-layers)。
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/api-integration/endpoint-behaviors/inbox-credit-quota-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
