权益 API

​

Scope

​

查询团队成员当前周期用量

POST /open/v1/team/entitlements/member-usage/current
Content-Type: application/json

{
  "member_id": "tm_Kx7Qm2pV9sRa4nBt6cWd8Y",
  "codes": ["max_projects", "sandbox_runtime"]
}

• member_id（string，必填）：团队成员公开 ID，格式为 tm_...，使用团队成员 API 返回的真实成员编号。不能传秒悟内部用户 ID 或阿里云 OpenID。
• codes（string[ ]，可选）：待查询的权益 code 列表。省略或传 [ ] 时查询全部支持项；重复 code 去重，按首次出现的顺序返回。传入任一不支持的 code，整个请求返回参数错误；null 不等同于空数组。

{
  "member_id": "tm_Kx7Qm2pV9sRa4nBt6cWd8Y"
}

{
  "member_id": "tm_Kx7Qm2pV9sRa4nBt6cWd8Y",
  "start_time": "2026-09-03T00:00:00",
  "end_time": "2026-10-03T00:00:00",
  "items": [
    {
      "code": "max_projects",
      "name": "项目数量",
      "used": 3,
      "unit": "个"
    },
    {
      "code": "sandbox_runtime",
      "name": "构建沙箱",
      "used": 120.5,
      "unit": "分钟"
    }
  ]
}

• member_id（string）：本次查询的公开成员 ID，与请求值一致。
• start_time（string）：主账号当前账期的开始时间。
• end_time（string）：主账号当前账期的结束时间。
• items（object[ ]）：权益使用量明细，每项包含：
  • code（string）：权益 code。
  • name（string）：权益展示名。
  • used（number）：实际使用量，非负数，可包含小数。
  • unit（string）：用量单位，例如“个”“分钟”“GB”“次”。

• 主账号及当前账期由服务端根据团队凭证解析，调用方无需也不能传入时间。
• start_time、end_time 保留账期服务返回的本地时间字符串，可带小数秒；不是 Unix epoch 毫秒时间戳，不额外附加或转换时区。
• 只有配置为 MONTHLY 的计量项使用该账期的开始、结束时间；其他周期类型（如 NONE）保持原有计量语义，不传账期过滤时间。因此，不能将顶层账期理解为所有 items 均在该区间内累计。
• 查询不按套餐是否包含该 code 或额度值（如 0、-1）进行拦截；但主账号必须满足 ACTIVE Open 准入要求。
• 任一项查询失败、配置缺失或返回无效用量时，整个请求失败；不返回部分明细，也不把异常用量降级为 0。

​

查询团队当前周期用量

POST /open/v1/team/entitlements/team-usage/current
Content-Type: application/json

{
  "codes": ["max_projects", "sandbox_runtime"]
}

• codes（string[ ]，可选）：查询范围与上文成员接口相同，共用 7 项权益白名单。省略或传 [ ] 查询全部支持项；重复项去重，按首次出现的顺序返回。
• 不接受 member_id、内部成员 ID、主账号或起止时间字段；传入这些额外字段会返回 400 invalid_request，不会静默忽略。
• 请求体为 JSON 对象。查询全部权益可发送 {} 或 {"codes":[ ]}；codes:null 不等同于空数组。

{
  "start_time": "2026-09-03T00:00:00",
  "end_time": "2026-10-03T00:00:00",
  "items": [
    {
      "code": "max_projects",
      "name": "项目数量",
      "used": 12,
      "unit": "个"
    },
    {
      "code": "sandbox_runtime",
      "name": "构建沙箱",
      "used": 360.5,
      "unit": "分钟"
    }
  ]
}

• start_time（string）：主账号当前账期的开始时间。
• end_time（string）：主账号当前账期的结束时间。
• items（object[ ]）：团队整体权益用量明细，每项包含 code、name、used、unit，含义与成员接口一致。
• 响应不包含 member_id、owner_id 或内部用户 ID，既不在顶层返回，也不在明细中返回。

• 同样仅支持主账号拥有 ACTIVE Open 权益的团队；普通 Team、个人版及无有效权益均不允许查询。
• 服务端不读取目标成员关系，也不添加成员过滤条件；该接口不要求先创建或选择某个成员。
• 使用主账号当前账期原值，不重新计算或转换时区。只有配置为 MONTHLY 的计量项使用该账期；其他周期（如 NONE）保持原计量语义。“当前周期”不表示所有权益项都按该账期累计。
• 不按套餐是否包含 code 或额度值进行拦截。任一项查询失败、配置缺失或返回无效用量时，整个请求返回错误，不交付部分数据，不将异常降级为 0。
• 错误格式与下方“常见错误”一致；成员归属相关的 404 not_found 仅适用于成员用量接口。

​

常见错误

{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "权益用量服务暂不可用",
  "code": "service_unavailable",
  "trace_id": "example_trace_id"
}