终端用户用量查询和配额管控（API）

本文介绍如何通过扣子 API 对终端用户配额进行管控，并导出终端用户的用量数据。

前提条件

• 套餐限制：企业旗舰版、原企业版。
• 设备信息上报：确保企业下的设备已成功上报了设备信息，否则权益额度将无法对该设备生效，设备信息的配置方法可参考设置设备信息。

创建设备权益额度

你可以创建设备的权益额度，以便用户在初始阶段免费体验设备功能，同时避免资源的过度使用。

场景描述和限制

设备权益额度的管控方式可以基于设备的设备 ID，也可以基于自定义维度的实体 ID。例如，在智慧教育等场景中，如果需要对 APP 中的用户进行配额管控。你可以在上报设备信息时，通过 custom_consumer 参数，设置上报的设备信息为 APP 对应的用户名，具体请参见上报设备信息。
本文以通过设备 ID 进行权益额度管控为例，介绍具体的实现方式。在设备配额管理中，通常需要针对企业中的所有设备创建累计可用积分额度和时间周期内的积分额度，同时针对个别设备设置累计可用积分额度。

场景一：为所有设备创建累计可用积分额度

为企业下所有设备设置累计可用积分额度。例如，设置企业中每个设备累计额度为 5000 积分，且该配额规则永久有效。当设备 A 的累计使用积分达到 5000 上限后，设备 A 将无法继续使用。实现方法如下：
调用创建用量限额配置 API，关键参数设置如下：

示例代码如下：

curl --location --request POST 'https://api.coze.cn/v1/commerce/benefit/limitations' \
--header 'Authorization: Bearer pat_YourAccessTokenHere' \
--header 'Content-Type: application/json' \
--data-raw '{
  "entity_type": "enterprise_all_devices",
  "benefit_info": {
    "benefit_type": "resource_point",
    "active_mode": "absolute_time",
    "started_at": 1743004800,
    "ended_at": 253402300799,
    "limit": 5000,
    "trigger_unit": "never"
  }
}'

场景二：为所有设备创建周期内可用积分额度

为企业中的所有设备创建一条时间周期内可用的积分额度。
例如，设置企业中每个设备每日可用额度为 1000 积分，且该配额规则永久有效。当设备 A 今天的使用积分达到 1000 上限后，设备 A 今天将无法继续使用，需等到次日才能恢复使用。
调用创建用量限额配置 API，关键参数设置如下：

示例代码如下：

curl --location --request POST "https://api.coze.cn/v1/commerce/benefit/limitations" \
--header 'Authorization: Bearer pat_YourAccessTokenHere' \
--header 'Content-Type: application/json' \
--data-raw '{
  "entity_type": "enterprise_all_devices",
  "benefit_info": {
    "benefit_type": "resource_point",
    "active_mode": "absolute_time",
    "started_at": 1743004800,
    "ended_at": 253402300799,
    "limit": 1000,
    "trigger_unit": "day",
    "trigger_time": 1
  }
}'

场景三：为单个设备创建累计可用积分额度

为特定设备单独设置累计额度，例如，设备 ID 为 SN12345 的设备，累计可用积分额度为 2000 积分。
调用创建用量限额配置 API，关键参数设置如下：

示例代码如下：

curl --location --request POST 'https://api.coze.cn/v1/commerce/benefit/limitations' \
--header 'Authorization: Bearer pat_YourAccessTokenHere' \
--header 'Content-Type: application/json' \
--data-raw '{
  "entity_type": "single_device",
  "entity_id": "SN12345*********",
  "benefit_info": {
    "benefit_type": "resource_point",
    "active_mode": "absolute_time",
    "started_at": 1743004800,
    "ended_at": 253402300799,
    "limit": 2000,
    "trigger_unit": "never"
  }
}'

场景四：为所有设备创建周期内可用语音和积分配额

如果企业购买了 AI 智能通话许可（系统音色）或 AI 智能通话许可（复刻音色），你可以创建语音通话时长配额。本文以为企业中的所有设备创建每日可用的语音通话时长配额和积分配额为例。当任一配额用尽后，设备在当前周期内将无法继续使用。
例如，智能体使用系统音色，你可以设置企业中每个设备每日可用语音通话时长配额（系统音色）​为 1200 秒，积分配额为 500 积分。当设备 A 今天使用的积分或语音通话时长任一个达到上限后，设备 A 今天将无法继续使用，需等到次日才能恢复使用。
你需要调用两次 API，分别为两种 benefit_type 创建配额规则。

1. 调用创建用量限额配置 API，配置语音通话时长配额，关键参数设置如下：

   参数	类型	说明
   entity_type	String	权益配额的生效范围。本场景中设置为 enterprise_all_devices，即权益配额对企业下的所有设备生效。
   benefit_info.benefit_type	String	权益额度类型，枚举值： resource_point：积分配额。 voice_unified_duration_system：语音通话时长配额（系统音色）。 voice_unified_duration_custom：语音通话时长配额（复刻音色）。
   benefit_info.started_at	Long	该条配额规则的生效起始时间，Unixtime 时间戳格式，单位为秒。 例如设置为 1756684800，对应 2025-09-01 00:00:00。
   benefit_info.ended_at	Long	该条配额规则的生效截止时间，Unixtime 时间戳格式，单位为秒。过期后，该条配额规则会失效。 例如设置为 253402300799，对应9999-12-31 ，表示永久有效。
   benefit_info.limit	Long	周期内可用的额度。 如果权益配额类型为 resource_point，可用额度的单位为积分。 如果权益配额类型为voice_unified_duration_system或voice_unified_duration_custom，可用额度的单位为秒。
   benefit_info.trigger_unit	String	权益可用额度的重置周期。本场景中设置为 day，以天为周期重置额度。
   benefit_info.trigger_time	Long	权益额度重置周期的频率。本场景中设置为 1，每日刷新配额。

   示例代码如下：

   curl --location --request POST "https://api.coze.cn/v1/commerce/benefit/limitations" \
   --header 'Authorization: Bearer pat_YourAccessTokenHere' \
   --header 'Content-Type: application/json' \
   --data-raw '{
     "entity_type": "enterprise_all_devices",
     "benefit_info": {
       "benefit_type": "voice_unified_duration_system",
       "active_mode": "absolute_time",
       "started_at": 1756684800,
       "ended_at": 253402300799,
       "limit": 1200,
       "trigger_unit": "day",
       "trigger_time": 1
     }
   }'
   

2. 调用创建用量限额配置 API，配置积分配额，示例代码如下：

   curl --location --request POST "https://api.coze.cn/v1/commerce/benefit/limitations" \
   --header 'Authorization: Bearer pat_YourAccessTokenHere' \
   --header 'Content-Type: application/json' \
   --data-raw '{
     "entity_type": "enterprise_all_devices",
     "benefit_info": {
       "benefit_type": "resource_point",
       "active_mode": "absolute_time",
       "started_at": 1756684800,
       "ended_at": 253402300799,
       "limit": 500,
       "trigger_unit": "day",
       "trigger_time": 1
     }
   }'
   

相关 API

• 更新设备权益额度：您可以通过调用更新用量限额配置 API，修改某条设备权益配额。
• 查询设备权益额度：您可以通过调用查询用量限额配置 API，查询已配置的权益额度信息。

设备用量查询

通过设备用量查询，你可以查看智能设备的用量明细，包括：语音识别 ASR 的音频时长、语音合成 TTS 的字符数、语音合成 TTS 的对话次数、RTC 通话时长、消耗的积分等信息。

步骤一：导出设备账单

调用导出终端用户账单 API，创建导出设备账单的任务。
该 API 为异步接口，若账单数据量较大，可能需等待约 1 分钟，当任务状态为 succeed 时，才会返回账单的下载链接。
示例代码如下：

curl --location --request POST 'https://api.coze.cn/v1/commerce/benefit/bill_tasks' \
--header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
--header 'Content-Type: application/json' \

 \
--data-raw '-d '{
  "started_at": 1743004800,
  "ended_at": 1743091200
}''

步骤二：查询账单文件

当导出设备账单的任务状态为 succeed 时，可以调用查询账单文件 API 查询账单文件，获取对应账单文件的 URL 链接，以便下载或查看已导出的账单数据。
示例代码如下：

curl --location --request GET 'https://api.coze.cn/v1/commerce/benefit/bill_tasks?page_num=1&page_size=50' \
--header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
--header 'Content-Type: application/json'

账单字段说明

账单文件中的字段说明请参见账单推送回调事件。