文档中心

TRAE CN

用量管理

设置成员的个人用量限额

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

所需权限

quota:write

请求说明

请求方式：POST

请求地址：{域名}/openapi/v1/quota/set_user_usage_quota

生效规则

若已为成员配置个人用量限额，该个人限额将优先于企业人均用量限额生效；同时，企业整体用量限额或共享额度池总额仍会继续约束成员的实际可用额度。

本接口采用部分更新机制，仅更新请求中显式传入的额度参数：

未传入某个限额参数：保留该成员当前对应维度的个人用量限额配置。

未传入某个模型：保留该成员当前对应模型的个人用量限额配置。

在模型数组中传入模型展示名：若该模型已存在个人用量限额配置，则更新对应额度；若不存在，则追加该模型的个人用量限额配置。

显式传入 0：将该成员在对应维度的用量限额设置为“不限制”。此时，该成员不再受该维度企业人均用量限额约束，但仍受企业整体用量限额或共享额度池总额约束。

传入正整数：为该成员在对应维度设置具体的个人用量限额。

当前接口不支持直接清除成员的个人用量限额配置。如需恢复企业默认的用量限额配置，需在 TRAE 企业版控制台的 “用量管理” 面板中使用 “恢复默认配额” 功能，详情参考此文档。

前置条件

确认企业当前的限额配置颗粒度（quota_granularity），该配置将决定本接口中可生效的限额参数。

方式一（推荐）：

调用 “查询成员的个人用量限额” 接口。

方式二：

若文案为 “已配置模型级限额”，则表明 quota_granularity 为 per_model。

若文案为 “企业限额 ¥x；人均限额 ¥x”，则表明 quota_granularity 为 all。

若显示 “无企业限额” 或 “无人均限额”，quota_granularity 仍可能为 all，只是尚未设置具体数值。

请求参数

请求头参数

Header 参数	是否必填	描述
Authorization	是	固定取值为 Bearer {access_token}。关于如何获取访问令牌，参考鉴权。
Content-Type	是	固定取值为 application/json。

请求体参数

参数	类型	是否必填	描述
emails	string[]	条件必填	目标成员的邮箱列表。与 user_ids 至少传入一个。成员的邮箱可以通过 “获取成员列表” 接口获取。
user_ids	string[]	条件必填	目标成员的 ID 列表。与 emails 至少传入一个。成员的 ID 可以通过 “获取成员列表” 接口获取。
trae_model_quota_type	string	是	企业当前对 TRAE 内置模型采用的用量计算模式。取值： token：按 Token 计，仅对旧企业版套餐有效。 price：按金额计（单位：元），仅对新企业版套餐有效。
basic_quota	int64	否	成员可用的基础会话额度。取值范围：[0, 企业整体限额]。取值为 0 时，表示不设置限额。该额度来自共享额度池，仅对旗舰版套餐和 TRAE 内置模型生效。详情参考共享额度池。
total_excess_quota	int64	否	成员使用 TRAE 内置模型时，可用的全部模型总超额会话额度。取值范围：[0, 9999999998]。取值为 0 时，表示不设置限额。提示：仅当 quota_granularity 为 all 时，该参数有效。
trae_model_excess_quota	array	否	成员使用 TRAE 内置模型时，指定单个模型可用的超额会话额度。提示：仅当 quota_granularity 为 per_model 时，该参数有效。
trae_model_excess_quota.name	string	是	TRAE 内置模型的展示名，区分大小写，须与模型列表中的名称完全一致。
trae_model_excess_quota.quota	int64	是	成员在指定 TRAE 内置模型中可用的超额会话额度。旧企业版套餐的单位为 Token，新企业版套餐的单位为元。取值范围：[0, 9999999998]。取值为 0 时，表示不设置限额。
custom_model_excess_quota	array	否	成员使用企业内置模型时，可用的额度。该参数生效与否不受 quota_granularity 限制。
custom_model_excess_quota.name	string	是	企业内置模型的展示名，区分大小写，须与模型列表中的名称完全一致。
custom_model_excess_quota.token_quota	int64	是	成员在指定企业内置模型中可用的额度，单位为 Token。取值范围：[0, 9999999998]。取值为 0 时，表示不设置限额。

注意事项

单次请求支持同时传入 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 参数中不得传入重复的模型名称，否则请求将失败。

使用建议

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

响应参数

所传入的成员的个人用量限额都更新成功时，该接口仅返回通用响应参数。参数说明参考通用响应格式。

若仅部分成员的用量限额更新成功，该接口会返回以下特有参数：

参数	类型	描述
succeeded_users	string[]	个人用量限额更新成功的成员的用户 ID 列表。
failed_users	string[]	个人用量限额更新失败的成员的用户 ID 列表。
error_detail	string	错误说明。

示例

请求示例

仅修改可用的总超额会话额度：

curl -X POST "${HOST}/openapi/v1/quota/set_user_usage_quota" \​
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \​
  -H "Content-Type: application/json" \​
  -d '{​
    "user_ids": ["123456", "654321"],​
    "trae_model_quota_type": "token",​
    "total_excess_quota": 50000000​
  }'​

响应示例

全部更新成功：

{​
  "code": 0,​
  "message": "success",​
  "request_id": "req_xxx",​
  "data": null​
}​

部分更新成功：

{​
  "code": 60110,​
  "message": "partial success",​
  "request_id": "req_xxx",​
  "data": {​
    "succeeded_users": ["123456"],​
    "failed_users": ["654321"],​
    "error_detail": "update quota failed"​
  }​
}​

错误码

若该接口的请求返回错误码，参考错误码文档进行排查。

最近更新时间：2026.10.10 17:34:31

这个页面对您有帮助吗？

有用

无用