扣子

扣子扣子编程扣子罗盘资源

文档反馈

低代码项目

快速开始

智能体

工作流

应用

资源

发布

模型

多人协作

开发工具

Coze CLI

API 参考

鉴权

智能体和应用

工作空间

文件夹

企业/组织

会话与消息

对话

工作流

文件

智能音视频

知识库

数据库

插件

变量

渠道

用量限额

创建用量限额配置

查询用量限额配置

更新用量限额配置

账单与权益

回调

错误码

API 教程

API 常见问题

SDK 参考

音视频

推广与变现

常见问题

更新用量限额配置

更新于: 2026-06-25 19:29:14

更新用量限额配置。

说明

套餐限制：扣子企业旗舰版。
角色限制：企业超级管理员和管理员可以调用该 API。

接口描述

企业超级管理员和管理员可以调用该 API 更新已创建的用量限额配置。

针对设备的终端用户，更新积分用量限额或 AI 智能通话语音时长用量限额。
针对企业内的成员、空间、组织，更新积分用量限额。

接口限制

在更新企业成员、空间、组织的积分限额时，更新 starttime、endtime 和 trigger_time 字段无效，系统会自动忽略这些配置。

积分累计额度：设置 trigger_unit 为 never。
积分每月额度：设置 trigger_unit 为除 never 以外的其他可选值，系统将自动转化为自然月周期。

基础信息

请求方式 PUT

请求方式	PUT
请求地址	`https://api.coze.cn/v1/commerce/benefit/limitations/:benefit_id`
权限	`updateBenefitLimitation` 确保调用该接口使用的访问令牌开通了 `updateBenefitLimitation` 权限，详细信息参考鉴权方式。
接口说明	更新用量限额配置。

请求地址

https://api.coze.cn/v1/commerce/benefit/limitations/:benefit_id

权限

updateBenefitLimitation

确保调用该接口使用的访问令牌开通了 updateBenefitLimitation 权限，详细信息参考鉴权方式。

接口说明 更新用量限额配置。

请求参数

参数	取值	说明
Authorization	Bearer $Access_Token	用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考准备工作。
Content-Type	application/json	用于指定解析请求正文的格式，表明请求体为 JSON 格式数据。

Path

参数	类型	是否必选	示例	说明
benefit_id	String	可选	123	用量限额配置的 ID。你可以在创建用量限额配置的返回参数中获取。

Body

参数	类型	是否必选	示例	说明
active_mode	String	可选	absolute_time	激活模式，当前仅支持设置为 `absolute_time` ，即绝对时间。该模式下，权益生效时间由 `started_at` 和 `ended_at` 两个时间确定。
started_at	Long	可选	1743213600	用量限额配置的生效起始时间，Unixtime 时间戳格式，单位为秒。
ended_at	Long	可选	1743386400	用量限额配置的生效截止时间，Unixtime 时间戳格式，单位为秒。过期后，该限制配置会失效。
limit	Long	可选	100	用量限额。
status	String	可选	valid	用量限额配置的状态，枚举值： `valid`：（默认值）正常使用。 `frozen`：已冻结。 `cancel`：已取消。
trigger_unit	String	可选	day	用量限额的重置周期单位，系统将根据指定时间间隔重置限额。枚举值： `never`：不重置额度，适用于设置累计可用额度上限。 `minute`：以分钟为周期重置额度。 `hour`：以小时为周期重置额度。 `day`：以天为周期重置额度。
trigger_time	Long	可选	1	用量限额的重置频率。当 `trigger_unit` 为 `never` 时，`trigger_time` 值为 1，无实际意义。当 `trigger_unit` 为 `minute`、`hour` 或 `day` 时，`trigger_time` 表示具体的刷新频率，例如：`trigger_unit=day` 且 `trigger_time = 1`，表示每日刷新限额。

返回参数

参数	类型	示例	说明
code	Long	0	调用状态码。0 表示调用成功，其他值表示调用失败，你可以通过 msg 字段判断详细的错误原因。
msg	String	“”	状态信息。API 调用失败时可通过此字段查看详细错误信息。状态码为 0 时，msg 默认为空。
detail	Object of ResponseDetail	-	响应详情信息。

参数

类型

示例

说明

code

Long

调用状态码。0 表示调用成功，其他值表示调用失败，你可以通过 msg 字段判断详细的错误原因。

msg

String

“”

状态信息。API 调用失败时可通过此字段查看详细错误信息。

状态码为 0 时，msg 默认为空。

detail

Object of ResponseDetail

响应详情信息。

ResponseDetail

参数	类型	示例	说明
logid	String	20241210152726467C48D89D6DB2****	本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此`logid`及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。

示例

请求示例

curl --location --request PUT 'https://api.coze.cn/v1/commerce/benefit/limitations/12345***' \
--header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
--header 'Content-Type: application/json'
{
  "benefit_id": "12345***",
  "active_mode": "absolute_time",
  "started_at": 1741708800,
  "ended_at": 1741708800,
  "limit": 100,
  "status": "valid"
}

返回示例

{
  "data": {
    "benefit_id": "12345***",
    "benefit_type": "resource_point",
    "active_mode": "absolute_time",
    "started_at": 1741708800,
    "ended_at": 1741708800,
    "limit": 100,
    "status": "valid"
  },
  "code": 0,
  "msg": ""
}

错误码

如果成功调用扣子编程的 API，返回信息中 code 字段为 0。如果状态码为其他值，则表示接口调用失败。此时 msg 字段中包含详细错误信息，你可以参考错误码文档查看对应的解决方法。