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

前置条件

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

方式一（推荐）：
调用 “查询成员的个人用量限额” 接口。
方式二：
登录 TRAE 企业版控制台，前往 企业管理 > 用量管理 > 用量看板 > TRAE 内置模型，然后查看 超额会话 卡片下方的文案。
- 若文案为 “已配置模型级限额“，则表明 quota_granularity 为 per_model。
- 若文案为 ”企业限额 ¥x；人均限额 ¥x“，则表明 quota_granularity 为 all。
- 若显示 “无企业限额” 或 “无人均限额”，quota_granularity 仍可能为 all，只是尚未设置具体数值。

请求体

参数说明

参数	类型	是否必填	描述
`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": ["123456789012345678"],
    "trae_model_quota_type": "token",
    "total_excess_quota": 50000000
  }'

响应示例

全部更新成功：

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

部分更新成功：

{
  "code": 60110,
  "message": "partial success",
  "request_id": "req_abc123xyz",
  "data": {
    "succeeded_users": ["123456789012345678"],
    "failed_users": ["223456789012345678"],
    "error_detail": "update quota failed"
  }
}

错误码

关于该接口可能返回的错误码，参考错误码。

Was this document helpful?