> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trae.cn/llms.txt
> Use this file to discover all available pages before exploring further.

为指定成员设置个人用量限额，包括 TRAE 内置模型和企业内置模型的限额配置。

## 所需权限 {#hP2osxhEu}

`quota:write`

## 请求说明 {#haqOgRMvL}

* 请求方式：POST
* 请求地址：{域名}/openapi/v1/quota/set_user_usage_quota

## 请求体 {#hKMESXSGw}

### 参数说明 {#hX5a2njgx}

<!-- @cols-width: 237,100,100,477 -->
| | | | | \
|**参数** |**类型** |**是否必填** |**描述** |
|---|---|---|---|
|`emails` |string[] |条件必填 |待设置用量限额的成员的邮箱。与 `user_ids` 至少传入一个。邮箱不区分大小写。 |
|`user_ids` |string[] |条件必填 |待设置用量限额的成员的用户 ID。与 `emails` 至少传入一个。 |\
| | | | |\
| | | |你需要调用 “获取成员列表” 接口来获取成员的用户 ID，详情参考[获取成员列表](/enterprise_get-user-list)。 |
|`trae_model_quota_type` |string |是 |企业当前对 TRAE 内置模型采用的用量计算模式。取值： |\
| | | | |\
| | | |* `token` ：按 Token 计，仅对旧企业版套餐有效。 |\
| | | |* `price`：按金额计（单位：元），仅对新企业版套餐有效。 |
|`basic_quota` |int64 |否 |该成员可用的基础会话额度。 |\
| | | | |\
| | | |取值范围：[0, 企业整体限额]。取值为`0` 时，表示不设置限额。 |\
| | | | |\
| | | |该额度来自共享额度池，仅对旗舰版套餐和 TRAE 内置模型生效。详情参考[共享额度池](/enterprise_pooled-usage)。 |
|`total_excess_quota` |int64 |否 |成员使用 TRAE 内置模型时，可用的全部模型总超额会话额度。 |\
| | | | |\
| | | |取值范围：[0, 9999999998]。取值为`0` 时，表示不设置限额。 |\
| | | | |\
| | | |***提示***：仅当 `quota_granularity` 为 `all` 时，该参数有效。 |
|`trae_model_excess_quota` |array |否 |成员使用 TRAE 内置模型时，指定单个模型可用的超额会话额度。 |\
| | | | |\
| | | |***提示***：仅当 `quota_granularity` 为 `per_model` 时，该参数有效。 |
|`custom_model_excess_quota` |array |否 |成员使用企业内置模型时，可用的额度。该参数生效与否不受 `quota_granularity` 限制。 |

`trae_model_excess_quota` 数组包含以下参数：

<!-- @cols-width: 145,100,100,567 -->
| | | | | \
|**参数** |**类型** |**是否必填** |**描述** |
|---|---|---|---|
|`name` |string |是 |TRAE 内置模型的展示名，区分大小写，须与模型列表中的名称完全一致。 |
|`quota` |int64 |是 |成员在指定 TRAE 内置模型中可用的超额会话额度。 |\
| | | | |\
| | | |旧企业版套餐的单位为 Token，新企业版套餐的单位为元。 |\
| | | | |\
| | | |取值范围：[0, 9999999998]。取值为 `0` 时，表示不设置限额。 |

`custom_model_excess_quota` 数组包含以下参数：

<!-- @cols-width: 142,100,100,569 -->
| | | | | \
|**参数** |**类型** |**是否必填** |**描述** |
|---|---|---|---|
|`name` |string |是 |企业内置模型的展示名，区分大小写，须与模型列表中的名称完全一致。 |
|`token_quota` |int64 |是 |成员在指定企业内置模型中可用的额度，单位为 Token。 |\
| | | | |\
| | | |取值范围：[0, 9999999998]。取值为 `0` 时，表示不设置限额。 |

### 个人用量限额的更新与生效规则 {#hnppHKLmA}

* 若已为成员配置个人用量限额，该个人限额将优先于企业人均用量限额生效；同时，企业整体用量限额或共享额度池总额仍会继续约束成员的实际可用额度。
* 本接口采用部分更新机制，仅更新请求中显式传入的额度参数：
   * 未传入某个限额参数或模型：保留该成员当前对应维度的个人用量限额配置。
   * 显式传入 `0`：将该成员在对应维度的用量限额设置为“不限制”。此时，该成员不再受该维度企业人均用量限额约束，但仍受企业整体用量限额或共享额度池总额约束。
   * 传入正整数：为该成员在对应维度设置具体的个人用量限额。
* 当前接口不支持直接清除成员的个人用量限额配置。如需恢复企业默认的用量限额配置，需在 TRAE 企业版控制台的 “用量管理” 面板中使用 “恢复默认配额” 功能，详情参考[此文档](https://docs.trae.cn/enterprise_check-usage-for-enterprise#3fc64464)。

### 注意事项 {#hmkEn9WCv}


* 单次请求支持同时传入 `emails` 和 `user_ids` 参数。系统会根据邮箱或用户 ID 解析成员，并对重复成员自动去重。去重后，单次请求最多支持传入 50 个成员。
* `total_excess_quota` 与 `trae_model_excess_quota` 参数互斥，单次请求只能传入其中一个。请根据企业当前的 `quota_granularity` 类型选择对应参数。
* 请求中至少需传入以下限额参数之一：`basic_quota`、`total_excess_quota`、`trae_model_excess_quota` 或 `custom_model_excess_quota`，否则请求将失败。
* 限额数值须为 `0` 或正整数，否则请求将失败。
* `name` 参数中不得传入重复的模型名称，否则请求将失败。

### 使用建议 {#hxtTdgDeD}

当 `trae_model_quota_type` 为 `token` 时，系统会将正数限额值按 10000 Token 的精度向下取整。建议所有以 Token 为单位的限额值均传入 10000 的整数倍，以避免精度损失。

## 响应参数 {#hGpcZJcVd}

该 OpenAPI 仅返回通用响应参数。参数说明参考[通用响应格式](/enterprise_general-response-schema)。

## 请求示例 {#hx11gUh9b}

```JSON
{
  "emails": ["john@example.com"],
  "user_ids": ["12345"],
  "trae_model_quota_type": "price",
  "basic_quota": 20,
  "trae_model_excess_quota": [
    {
      "name": "Deepseek-V4",
      "quota": 3000
    }
  ],
  "custom_model_excess_quota": [
    {
      "name": "Enterprise-GPT",
      "token_quota": 10000000
    }
  ]
}
```

## 响应示例 {#hqUuhHF49}

```JSON
{
  "code": 0,
  "message": "success",
  "request_id": "req_abc123xyz",
  "data": null
}
```

## 错误码 {#hHxruQIHO}

关于该 OpenAPI 可能返回的错误码，参考[错误码](/enterprise_error-codes)。

## 如何查询企业当前的 `quota_granularity`？ {#hCsouoAfZ}

查询企业当前的 `quota_granularity` 的方式如下：

* **方式一（推荐）**：
   调用 “[查询成员的用量限额](/enterprise_query-usage-limits-for-members)” 这一 OpenAPI。
* **方式二**：
   登录 TRAE 企业版控制台，前往 **企业管理** > **用量管理** > **用量看板** > **TRAE 内置模型**，然后查看 **超额会话** 卡片下方的文案。
   * 若文案为 “已配置模型级限额“，则表明 `quota_granularity` 为 `per_model`。
   * 若文案为 ”企业限额 ¥x；人均限额 ¥x“，则表明 `quota_granularity` 为 `all`。
   * 若显示 “无企业限额” 或 “无人均限额”，`quota_granularity` 仍可能为 `all`，只是尚未设置具体数值。
      ![Image=2544x578](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/0ae0b5f8361f41e09eab91c3dbc87e19~tplv-goo7wpa0wc-topic.png)