账单报表

查询当前 API Key 在指定日期范围内的实际花销，按计费模型返回费用、Token 用量及请求数，适用于定时对账和成本统计。

本接口属于 HaoAI OpenAPI。一个 Key 只能查询自己的费用，不会返回同账户或同团队其他 Key 的账单。

端点


GET https://hao.ai/api/v1/usage/billing-report

使用站点域名 hao.ai 请求此接口。

认证

使用控制台创建的 API Key，通过请求头传入：


Authorization: Bearer sk-haoai-...

兼容已有的 sk-pohu-... Key，查询无需账户有正余额。 Key 必须有效、未禁用且未过期；如果配置了 IP 白名单，脚本出口 IP 必须在允许范围内。

API Key 只获得当前 Key 的报表读取权限，不包含其他 Key 的费用。此接口返回 JSON 报表；请通过请求头传递密钥，不要放在 URL 中。

请求参数

所有参数通过 query string 传入。日账单建议使用 start_date、end_date 和 timezone。

参数	类型	必填	说明
`start_date`	string	与 `end_date` 成对	起始日期，格式为 `YYYY-MM-DD`，包含当天
`end_date`	string	与 `start_date` 成对	结束日期，格式为 `YYYY-MM-DD`，包含当天
`timezone`	string	否	IANA 时区，例如 `Asia/Shanghai`；默认 `UTC`
`range`	string	否	预设日期范围，例如 `yesterday`、`7d`、`30d`；默认 `30d`
`from`、`to`	integer	`range=custom` 时	Unix 毫秒时间戳，按指定时区归入日历日期，包含 `to` 所在的整天
`model`	string	否	实际计费模型 ID；省略时返回该 Key 使用过的全部模型

range 可选值为 12h、24h、48h、today、yesterday、2daysago、3d、7d、14d、30d、90d、thismonth、lastmonth、custom。本报表按日历窗口解析：12h、24h 等同 today，48h 为昨天和今天。建议使用明确的日期或 yesterday。传入日期对时优先使用日期对，不要混用多种范围表达。

一次查询窗口最长 90 天，仅返回当前 API Key 自身的费用。未知或重复参数返回 400。

每天、每个模型的实际费用

将 start_date 和 end_date 设为同一天即可获得当天各模型的 actual_cost。需要多天明细时逐日查询；一个跨日请求返回整段时间汇总，不会自动拆成每天，也不支持 granularity / group_by。

例如，2026-10-05 配合 Asia/Shanghai 表示该时区 10 月 5 日 00:00 至次日 00:00，响应 range 会转换为 UTC，结束时间不包含在窗口内。

请求示例

cURL

Terminal


curl --get 'https://hao.ai/api/v1/usage/billing-report' \
  -H "Authorization: Bearer $HAOAI_API_KEY" \
  --data-urlencode 'start_date=2026-10-05' \
  --data-urlencode 'end_date=2026-10-05' \
  --data-urlencode 'timezone=Asia/Shanghai'

Python

billing_report.py


import os
from decimal import Decimal
 
import requests
 
resp = requests.get(
    "https://hao.ai/api/v1/usage/billing-report",
    headers={"Authorization": f"Bearer {os.environ['HAOAI_API_KEY']}"},
    params={
        "start_date": "2026-10-05",
        "end_date": "2026-10-05",
        "timezone": "Asia/Shanghai",
    },
    timeout=10,
)
resp.raise_for_status()
report = resp.json(parse_float=Decimal)["data"]
for row in report["rows"]:
    print(f"{row['model']}: ${row['actual_cost']:.6f}")
print(f"Total: ${report['totals']['actual_cost']:.6f}")

TypeScript

billing-report.ts


const params = new URLSearchParams({
  start_date: '2026-10-05',
  end_date: '2026-10-05',
  timezone: 'Asia/Shanghai',
})
const resp = await fetch(`https://hao.ai/api/v1/usage/billing-report?${params}`, {
  headers: { Authorization: `Bearer ${process.env.HAOAI_API_KEY}` },
  signal: AbortSignal.timeout(10_000),
})
if (!resp.ok) {
  throw new Error(`Billing report failed: HTTP ${resp.status}`)
}
const { data: report } = await resp.json()
for (const row of report.rows) {
  console.log(`${row.model}: $${row.actual_cost.toFixed(6)}`)
}
console.log(`Total: $${report.totals.actual_cost.toFixed(6)}`)

响应格式

成功响应 200 OK：


{
  "code": 0,
  "message": "success",
  "data": {
    "currency": "USD",
    "range": {
      "from": "2026-10-04T16:00:00Z",
      "to": "2026-10-05T16:00:00Z"
    },
    "rows": [
      {
        "api_key_id": "63a7f4c1-1542-4a65-a03e-4d0e15f71962",
        "api_key_name": "Production",
        "api_key_prefix": "sk-haoai-7fA3k9mB",
        "api_key_suffix": "hJv2",
        "model": "anthropic/claude-sonnet-4-5",
        "requests": 18,
        "input_tokens": 120000,
        "output_tokens": 45000,
        "cache_read_tokens": 12000,
        "cache_creation_tokens": 3000,
        "input_cost": 0.4,
        "output_cost": 0.8,
        "cache_read_cost": 0.1,
        "cache_creation_cost": 0.5,
        "search_cost": 0,
        "image_cost": 0,
        "video_cost": 0,
        "other_cost": 0,
        "actual_cost": 1.8,
        "official_cost": 3,
        "effective_discount": 0.6
      }
    ],
    "totals": {
      "requests": 18,
      "input_tokens": 120000,
      "output_tokens": 45000,
      "cache_read_tokens": 12000,
      "cache_creation_tokens": 3000,
      "input_cost": 0.4,
      "output_cost": 0.8,
      "cache_read_cost": 0.1,
      "cache_creation_cost": 0.5,
      "search_cost": 0,
      "image_cost": 0,
      "video_cost": 0,
      "other_cost": 0,
      "actual_cost": 1.8,
      "official_cost": 3,
      "effective_discount": 0.6
    }
  }
}

顶层与报表字段

字段	类型	说明
`code`	integer	成功时为 `0`
`message`	string	成功时为 `success`
`data.currency`	string	固定为 `USD`
`data.range.from`	string	UTC、RFC 3339 格式的窗口起点，包含该时刻
`data.range.to`	string	UTC、RFC 3339 格式的窗口终点，不包含该时刻
`data.rows`	array	当前 Key 按计费模型汇总的行，无用量时为空数组
`data.totals`	object	所有行的请求数、Token 和费用合计；无用量时为 0

`rows[]` 字段

字段	类型	说明
`api_key_id`	string	当前 Key 的公开 UUID
`api_key_name`	string	当前 Key 名称
`api_key_prefix`、`api_key_suffix`	string	用于展示的 Key 前缀和尾部字符，可能省略，不是完整密钥
`channel_name`	string	可选的当前渠道名称，仅作标识，不是独立结算组
`model`	string	实际计费模型 ID
`requests`	integer	请求数
`input_tokens`、`output_tokens`	integer	输入、输出 Token 数
`cache_read_tokens`、`cache_creation_tokens`	integer	缓存读取、创建 Token 数
`input_cost`、`output_cost`	number	输入、输出费用
`cache_read_cost`、`cache_creation_cost`	number	缓存读取、创建费用
`search_cost`、`image_cost`、`video_cost`、`other_cost`	number	搜索、图片、视频和其他费用
`actual_cost`	number	平台实际扣费，等于各费用分项之和
`official_cost`	number	对应请求的官方原价，不能当作实际扣费
`effective_discount`	number	`actual_cost / official_cost`，官方原价为 0 时省略

totals 包含同名的计数与费用字段，不包含 Key、渠道或模型标识。

金额单位为 USD，底层结算精度为 1 micro-USD（0.000001 USD）。统计实际花销请使用 actual_cost，不要使用当前模型单价重算历史账单。金额累加建议使用十进制定点方式。

报表与控制台使用同一份已处理用量聚合。刚结束的请求可能尚未反映在报表中，建议稍后补查；查询失败会返回错误，不会伪装成零费用。近期整点时区日账单可精确查询。超过小时聚合保留期（100 天）的历史窗口需要按 UTC 整日对齐；无法由保留的聚合粒度精确表达时返回 400。

频率限制

每分钟最多查询 3 次。请求过于频繁时返回 429。

建议串行发送请求，间隔至少 20 秒。收到 429 时，按 Retry-After 等待后重试。本接口响应带 Cache-Control: no-store，不应放入公共缓存。

错误响应

错误响应示例：


{
  "code": 429,
  "message": "too many requests",
  "reason": "rate_limited"
}

状态码	`reason`	说明
400	`validation_error` / `bad_request`	日期、时区、模型筛选或参数无效；窗口过大或无法精确查询
401	`unauthorized`	缺少 Key、Key 无效、禁用、过期、删除，或所属账户不可用
403	`apikey_ip_not_allowed`	当前出口 IP 不在 Key 白名单内
429	`rate_limited`	请求过于频繁，按 `Retry-After` 等待后重试
503	`service_unavailable`	服务暂时繁忙，按 `Retry-After` 重试
500	`internal_error`	查询失败或超时，稍后重试