--- title: "汇总账户用量与费用" description: "按时间范围查询 XiuAI 请求数、Token 和费用合计,并按模型与调用密钥分组。" image: "https://docs.xiu.ai/og.png" --- > XiuAI 文档索引 > 完整文档索引:https://docs.xiu.ai/llms.txt > 阅读前先通过索引确认当前可用页面。 # 汇总账户用量与费用 读取指定时间段的请求数、Token 和费用合计,并按模型与调用密钥名称分组。需要 `usage:read` 权限;尚未拿到密钥时,先在控制台[获取密钥](/open-api/#获取密钥)。 ```http GET /open/v1/requests/summary ``` ## 汇总参数 参数均为可选的 URL query 参数。 | 参数 | 类型 | 说明 | | --- | --- | --- | | `startTime` | integer | 开始时间,Unix 秒,包含该秒;默认比 `endTime` 早 24 小时 | | `endTime` | integer | 结束时间,Unix 秒,包含该秒;默认为当前时间 | | `model` | string | 模型名,精确匹配 | | `keyName` | string | 模型调用密钥名,精确匹配 | | `outcome` | string | `succeeded`、`interrupted` 或 `failed` | 时间窗最长 31 天,起止时间必须为正数,且开始时间不能晚于结束时间。更长区间分段查询后相加。由于边界均包含该秒,下一段的开始时间应为上一段结束时间加 1 秒,避免重复计算边界记录。 ```bash curl --fail-with-body --silent --show-error \ --connect-timeout 5 --max-time 15 --get \ https://api.xiu.ai/open/v1/requests/summary \ -H "Authorization: Bearer $XIU_OPEN_API_KEY" \ --data-urlencode "startTime=1794355200" \ --data-urlencode "endTime=1794441599" ``` ## 汇总字段 ```json { "startTime": 1794355200, "endTime": 1794441599, "requests": 1520, "succeeded": 1490, "interrupted": 6, "failed": 24, "promptTokens": 2840000, "completionTokens": 612000, "cost": "12.481250", "currency": "USD", "groups": [ { "model": "gpt-5", "keyName": "production", "requests": 1520, "succeeded": 1490, "interrupted": 6, "failed": 24, "promptTokens": 2840000, "completionTokens": 612000, "cost": "12.481250" } ] } ``` | 字段 | 类型 | 说明 | | --- | --- | --- | | `startTime`、`endTime` | integer | 实际统计的起止时间,已补全默认值,单位为 Unix 秒 | | `requests` | integer | 请求总数,等于 `succeeded + interrupted + failed` | | `succeeded`、`interrupted`、`failed` | integer | 各种结果的请求数,含义与请求记录一致 | | `promptTokens`、`completionTokens` | integer | 输入、输出 Token 合计,不计入失败请求 | | `cost` | string | 精确费用合计,固定六位小数 | | `currency` | string | 币种,当前为 `USD` | | `groups` | array | 按 `model`、`keyName` 排序的分组列表 | 每个分组包含字符串字段 `model`、`keyName`,以及该组的 `requests`、`succeeded`、`interrupted`、`failed`、`promptTokens`、`completionTokens` 和 `cost`,类型与上表一致。按模型或密钥统计时,将对应分组相加即可。 没有请求的时间窗返回零合计和空 `groups`。对账时,明细与汇总必须使用相同的时间和筛选条件;完整读取明细后,以十进制类型累加 `cost`,结果与汇总的 `cost` 一致。`requestId` 仅用于查询明细,不能作为汇总筛选条件。 需要查看合计对应的逐条数据时,使用[请求记录接口](/open-api/requests/)。重试方式见[错误与限频说明](/open-api/errors/)。 源文件:https://docs.xiu.ai/open-api/summary/index.mdx