Public API

在自己的计费工具中查询账户余额、模型用量与模型费用

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

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

异步生成任务(包括 Enterprise 模型)的状态查询见批量查询任务状态和 GET /tasks 接口参考。该接口遵循任务历史记录的读取权限,不接受下文的计费筛选参数或 scope。

Model API key required

这些计费接口使用模型 API Key(apikey-...),不接受管理 Key。

此对照仅比较两种 API Key;已启用的 OAuth scoped token 仍可按原规则用于计费查询。

接口

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

鉴权

在 Authorization header 中传入 Atlas Cloud API Key:

Authorization: Bearer $ATLASCLOUD_API_KEY

你可以在 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 $ATLASCLOUD_API_KEY"

金额会以 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_dateUTC 起始日期(含),格式为 YYYY-MM-DD
end_dateUTC 结束日期(不含),格式为 YYYY-MM-DD;最大查询范围为 180 天
scopeself 或 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 $ATLASCLOUD_API_KEY"

查询费用

/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 $ATLASCLOUD_API_KEY"

分页

当 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。

Last updated on

On this page