計費 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。

本頁目錄