用量与计量 API

本页涵盖两组端点：

1. 计量标签配置：声明按哪个 label key 拆分用量（租户级设置，owner 专属）
2. 按 label 维度查询用量：获取各 label 值（如各终端用户）的资源·秒消耗

---

应用场景

SaaS 集成方通常以一个租户账号接入 Talon Sandbox，代表平台内的所有终端用户创建 sandbox。此时：

• 每个 sandbox 打入 end_user_id 等标签（见 labels 详解）
• 配置计量标签键为 end_user_id
• 通过本页 API 查询每个终端用户的资源用量，用于二次计费 / 分账

---

计量标签配置

PUT /v1/billing/metering-label-key

声明该租户的用量按哪个 label key 拆分计量。

需要 owner 角色

PUT /v1/billing/metering-label-key
Authorization: Bearer ask_...
Content-Type: application/json

{
  "key": "end_user_id"
}

字段	类型	说明
key	string	用于拆分计量维度的 label key，需符合 label key 字符集（[a-zA-Z0-9_-]，长度 1–64）；传空串 "" 关闭按 label 计量

响应

204 No Content — 配置成功，无响应体

400 Bad Request — key 格式不合法

{ "error": "metering_label_key: invalid key format" }

仅 owner 可配置

计量标签键属于租户级账务配置，权限等级为 owner。admin 和 developer 角色无法修改。

---

按 label 维度查询用量

GET /v1/usage/by-label

查询按计量标签键拆分的资源用量。

需要 owner 角色

GET /v1/usage/by-label?since=2026-06-01T00:00:00Z&until=2026-06-08T00:00:00Z
Authorization: Bearer ask_...

查询参数：

参数	类型	必填	说明
since	RFC 3339	是	查询起始时间（含）
until	RFC 3339	是	查询截止时间（不含）

200 OK

{
  "since": "2026-06-01T00:00:00Z",
  "until": "2026-06-08T00:00:00Z",
  "label_key": "end_user_id",
  "groups": [
    {
      "label_value": "u_8821",
      "cpu_milli_seconds": 3600000,
      "memory_byte_seconds": 4294967296000,
      "disk_byte_seconds": 10737418240000,
      "sandbox_seconds": 3600
    },
    {
      "label_value": "u_1042",
      "cpu_milli_seconds": 1800000,
      "memory_byte_seconds": 2147483648000,
      "disk_byte_seconds": 5368709120000,
      "sandbox_seconds": 1800
    }
  ]
}

响应字段说明：

字段	类型	说明
since / until	string	实际查询的时间范围（回显请求参数）
label_key	string	本租户配置的计量标签键
groups	array	按 label_value 分组的用量列表
groups[].label_value	string	该分组对应的 label 值（如 u_8821）
groups[].cpu_milli_seconds	int64	CPU 毫核·秒（1000 = 1 core·秒）
groups[].memory_byte_seconds	int64	内存字节·秒（4GiB·1小时 ≈ 4×1024³×3600）
groups[].disk_byte_seconds	int64	磁盘字节·秒
groups[].sandbox_seconds	int64	sandbox 运行秒数（按 running 状态计时）

错误响应：

状态码	含义
400	since / until 格式不合法，或 since >= until
403	权限不足（非 owner 角色）
404	该租户未配置 metering_label_key
422	since–until 跨度超过系统允许的最大查询窗口

---

语义与限制

要点	说明
数据起点	计量从 metering_label_key 配置生效后的下一个计量节拍开始，不回填历史数据
仅配置租户有数据	未配置 metering_label_key 的租户调用此接口返回 404
未带标签的 sandbox	没有配置中指定 label key 的 sandbox，其用量只进入租户总账，不出现在 groups 列表中
租户总账	本接口仅返回 label 维度的分组视图，不等同于租户全量用量（总量 ≥ 各 group 之和）

---

典型集成示例

import os
import httpx
from datetime import datetime, timezone

base_url = os.environ["TALON_SANDBOX_SERVER"]
api_key  = os.environ["TALON_SANDBOX_API_KEY"]

headers = {"Authorization": f"Bearer {api_key}"}

# 1. 配置计量标签键（一次性，owner 执行）
httpx.put(
    f"{base_url}/v1/billing/metering-label-key",
    json={"key": "end_user_id"},
    headers=headers,
)

# 2. 查询本周用量
resp = httpx.get(
    f"{base_url}/v1/usage/by-label",
    params={
        "since": "2026-06-01T00:00:00Z",
        "until": "2026-06-08T00:00:00Z",
    },
    headers=headers,
)
data = resp.json()
for group in data["groups"]:
    cpu_core_hours = group["cpu_milli_seconds"] / 1000 / 3600
    print(f"用户 {group['label_value']}: {cpu_core_hours:.2f} core·h")

二次计费建议

• 建议每天定时拉取前一天数据并落库，避免单次查询窗口过大
• sandbox_seconds 适合按"活跃时间"计费；cpu_milli_seconds 适合按 CPU 用量计费