查询用量

返回指定时间段内、该 API Key 所属项目的消耗汇总：总额与按模型分项。消耗数据自动限定到 Key 所属的项目，不能跨项目查询。

鉴权

在请求头携带 API Key：

Authorization: Bearer sk_live_YOUR_API_KEY

接口

GET/api/business/v1/customer/usage

查询用量

Return aggregated usage (totals + per-model) for the API key's project over a time range. API key only.

Bearer API Key请求头使用 Authorization: Bearer sk_live_...，也支持 x-api-key。

请求结构

下方内容用于确认方法、地址和鉴权方式，属于 HTTP 结构片段，不是可独立执行示例。

HTTP

GET https://www.silvamux.com/api/business/v1/customer/usage
Authorization: Bearer $SILVAMUX_API_KEY

请求参数

参数	类型与位置	必填	说明
`Authorization`	string · header	是	Bearer API Key (sk_live_...)
`X-Organization-Id`	string · header	否	Not required for API key auth
`from`	string · query	是	RFC3339 start time (inclusive)
`to`	string · query	是	RFC3339 end time (exclusive)

响应

`200`OK

application/json · BillingUsageReportResponse

字段	类型	必填	说明
`$schema`	string (uri)	否	A URL to the JSON Schema for this object.
`by_model`	array<UsageReportModelBreakdown>	是	Per-model breakdown, ordered by cost_points desc
`by_model.billable_prompt_tokens`	integer (int64)	是	Summed billable prompt tokens
`by_model.cache_creation_tokens`	integer (int64)	是	Summed cache creation tokens
`by_model.cache_explicit_read_tokens`	integer (int64)	是	Summed explicit cache read tokens
`by_model.cached_tokens`	integer (int64)	是	Summed cached tokens
`by_model.completion_tokens`	integer (int64)	是	Summed completion tokens
`by_model.cost_points`	string	是	Total cost in points (after discount)
`by_model.generated_artifacts`	integer (int64)	是	Summed generated artifacts
`by_model.model`	string	是	Aggregation key: user-supplied request_model, falling back to the configured model ID for legacy rows
`by_model.original_cost`	string	是	Total cost in points before discount
`by_model.prompt_tokens`	integer (int64)	是	Summed prompt tokens
`by_model.request_count`	integer (int64)	是	Number of billed requests
`by_model.total_tokens`	integer (int64)	是	Summed total tokens
`from`	string (date-time)	是	Report start (RFC3339, inclusive)
`project_id`	string	是	Project filter ('' means org-wide)
`to`	string (date-time)	是	Report end (RFC3339, exclusive)
`totals`	UsageReportTotals	是	—
`totals.billable_prompt_tokens`	integer (int64)	是	—
`totals.cache_creation_tokens`	integer (int64)	是	—
`totals.cache_explicit_read_tokens`	integer (int64)	是	—
`totals.cached_tokens`	integer (int64)	是	—
`totals.completion_tokens`	integer (int64)	是	—
`totals.cost_points`	string	是	Total cost in points (after discount)
`totals.generated_artifacts`	integer (int64)	是	—
`totals.original_cost`	string	是	Total cost in points before discount
`totals.prompt_tokens`	integer (int64)	是	—
`totals.request_count`	integer (int64)	是	—
`totals.total_tokens`	integer (int64)	是	—

`default`Error

application/problem+json · ErrorModel

字段	类型	必填	说明
`$schema`	string (uri)	否	A URL to the JSON Schema for this object.
`detail`	string	否	A human-readable explanation specific to this occurrence of the problem.
`errors`	array<ErrorDetail>	否	Optional list of individual error details
`errors.location`	string	否	Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
`errors.message`	string	否	Error message text
`errors.value`	any	否	The value at the given location
`instance`	string (uri)	否	A URI reference that identifies the specific occurrence of the problem.
`status`	integer (int64)	否	HTTP status code
`title`	string	否	A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
`type`	string (uri)	否	A URI reference to human-readable documentation for the error.；默认值：about:blank

参数

from、to：必填，RFC3339 时间，左闭右开 [from, to)，from 必须早于 to。
时间范围以 UTC 为准。

示例

curl "https://www.silvamux.com/api/business/v1/customer/usage?from=2026-07-08T00:00:00Z&to=2026-07-09T00:00:00Z" \
  -H "Authorization: Bearer $SILVAMUX_API_KEY"

# pip install requests
import os
import requests

resp = requests.get(
    "https://www.silvamux.com/api/business/v1/customer/usage",
    params={
        "from": "2026-07-08T00:00:00Z",
        "to": "2026-07-09T00:00:00Z",
    },
    headers={"Authorization": f"Bearer {os.environ['SILVAMUX_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json()["totals"])

// Node 18+（内置 fetch）
const from = "2026-07-08T00:00:00Z";
const to = "2026-07-09T00:00:00Z";
const query = new URLSearchParams({ from, to });

const resp = await fetch(
  `https://www.silvamux.com/api/business/v1/customer/usage?${query}`,
  {
    headers: { Authorization: `Bearer ${process.env.SILVAMUX_API_KEY}` },
  },
);

const data = await resp.json();
console.log(data.totals);

// 仅依赖标准库
package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    url := "https://www.silvamux.com/api/business/v1/customer/usage?from=2026-07-08T00:00:00Z&to=2026-07-09T00:00:00Z"

    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer "+os.Getenv("SILVAMUX_API_KEY"))

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

响应：

{
  "from": "2026-07-08T00:00:00Z",
  "to": "2026-07-09T00:00:00Z",
  "project_id": "PROJ-1",
  "totals": {
    "cost_points": "1.5",
    "prompt_tokens": 100,
    "cached_tokens": 0,
    "billable_prompt_tokens": 100,
    "completion_tokens": 50,
    "cache_creation_tokens": 0,
    "total_tokens": 150,
    "generated_artifacts": 0,
    "request_count": 2
  },
  "by_model": [
    {
      "model": "deepseek-v4-pro@tune",
      "cost_points": "1.5",
      "prompt_tokens": 100,
      "cached_tokens": 0,
      "billable_prompt_tokens": 100,
      "completion_tokens": 50,
      "cache_creation_tokens": 0,
      "total_tokens": 150,
      "generated_artifacts": 0,
      "request_count": 2
    }
  ]
}

字段	说明
`project_id`	该 API Key 绑定的项目
`totals`	时间范围内所有模型的汇总
`by_model`	按模型分项，按 `cost_points` 降序

错误处理

HTTP 状态	错误码	说明
401	`INVALID_TOKEN`	API Key 缺失或无效
400	`INVALID_FROM_DATETIME`	`from` 缺失或格式非 RFC3339
400	`INVALID_TO_DATETIME`	`to` 缺失或格式非 RFC3339
400	`INVALID_TIME_RANGE`	`from` 不早于 `to`

查询用量

鉴权

接口

请求结构

请求参数

响应

200OK

defaultError

参数

示例

错误处理

`200`OK

`default`Error