计费 Public API

计费 Public API 用于从脚本、仪表盘和财务系统中读取 Atlas Cloud 计费数据。

Base URL: https://api.atlascloud.ai/public/v1

接口

Endpoint	说明
`GET /balance`	当前账户余额和授信汇总
`GET /model-usage`	按 UTC 日聚合的模型用量
`GET /model-costs`	按 UTC 日聚合的模型费用

完整请求和响应结构见 API 参考：

鉴权

在 Authorization header 中传入 Atlas Cloud API Key：

Authorization: Bearer apikey-...

你可以在 API Keys 创建 API Key。密钥本身以 apikey- 开头。

部分响应和过滤参数会使用 ak_... 形式的 API Key public ID。它可以展示在计费报表中，但不是凭证，不能用于请求鉴权。

权限

/model-usage 和 /model-costs 默认使用 scope=self，返回归属于鉴权用户的用量，包括该用户拥有的 API Key。

使用 scope=account 可以查询账户级用量和费用，但需要账户级模型计费读取权限。/balance 固定为账户级范围，需要账户余额读取权限。

个人账户 owner 可以读取自己的账户计费数据。团队账户建议使用 Account Admin 或 Finance 角色。

查询余额

curl "https://api.atlascloud.ai/public/v1/balance" \
  -H "Authorization: Bearer apikey-..."

金额会以 6 位小数字符串和 currency 返回：

{
  "value": "125.500000",
  "currency": "usd"
}

用量和费用查询参数

start_date 和 end_date 是必填的 UTC 日期，格式为 YYYY-MM-DD。end_date 为开区间，最大查询范围为 180 天。

/model-usage 和 /model-costs 的常用查询参数。省略 group_by[] 时返回按天汇总的总量：

参数	说明
`start_date`	UTC 起始日期（含），格式为 `YYYY-MM-DD`
`end_date`	UTC 结束日期（不含），格式为 `YYYY-MM-DD`；最大查询范围为 180 天
`scope`	`self` 或 `account`，默认 `self`
`group_by[]`	可选分组。支持 `model_type`、`model`、`api_key`，或 `model` 加 `api_key`；按模型拆分请传 `group_by[]=model`
`model_types[]`	可重复传入 `text`、`image` 或 `video`
`model_ids[]`	按模型 ID 过滤，最多 100 个
`api_key_ids[]`	按 `ak_...` API Key public ID 过滤，最多 100 个
`limit`	每页行数，1 到 1000，默认 100
`page`	来自 `next_page` 的不透明分页 cursor

数组参数必须使用重复参数形式。逗号分隔的值会被拒绝。

查询用量

默认响应返回按天汇总的用量总量。

curl "https://api.atlascloud.ai/public/v1/model-usage?start_date=2026-05-01&end_date=2026-05-08" \
  -H "Authorization: Bearer apikey-..."

查询费用

/model-costs 使用与 /model-usage 相同的日期范围、scope、过滤、分组和分页参数。省略 group_by[] 时返回按天汇总的费用总量。

curl "https://api.atlascloud.ai/public/v1/model-costs?start_date=2026-05-01&end_date=2026-05-08&scope=account&group_by[]=model&group_by[]=api_key" \
  -H "Authorization: Bearer apikey-..."

分页

当 has_more 为 true 时，把 next_page 原样作为 page 查询参数传回。cursor 是不透明值，请不要解析，并保持其他查询参数不变。

错误和限流

错误响应使用稳定结构：

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date",
    "message": "start_date must be YYYY-MM-DD",
    "param": "start_date"
  },
  "request_id": "req_..."
}

触发限流时返回 429 rate_limit_error，响应中可能包含 Retry-After header。

本页目录