帳單查詢與匯出

帳單統計依時間粒度彙總模型用量、次數及金額；Excel 用於儲存與離線核對。

準備存取權杖

在個人資料頁面的「安全」區域建立存取權杖，填入查詢帳單統計或匯出帳單的線上測試。

選擇時間與篩選條件

選擇統計粒度，例如「日」可查看每日彙總。
填入開始與結束的秒級 Unix 時間戳記，或使用右側日期選擇器。日期依瀏覽器本地時區換算；查詢整日請確認結束時間涵蓋當日。
只查特定 API Key 或模型時再填名稱；查看所有符合記錄時，兩項都留空。

篩選項	必填	使用方式
統計粒度 `type`	是	1=分鐘、2=小時、3=日、4=週、5=月
開始、結束時間	是	`startTime`、`endTime`，單位為秒；結束不可早於開始
API Key 名稱 `tokenName`	否	填名稱，不是密鑰或存取權杖；省略時不依名稱篩選
模型名稱 `modelName`	否	填實際模型名稱；省略時不依模型篩選

查詢與查看統計結果

在查詢帳單統計的線上測試提交條件。本文 code=200 表示業務成功，data 為彙總陣列，不是逐次呼叫紀錄。

time、timeGroup：記錄時間及秒級分組時間戳記。
callCount、totalUseTime：呼叫次數與累計耗時。
totalPromptTokens、totalCompletionTokens 與快取欄位：輸入、輸出與快取用量。
totalAmount：消費金額；詳細欄位及範例見 Reference，不要將 Token 用量直接當作金額。

code: 200、data: [] 表示查詢成功，但時間與條件沒有符合記錄。

選用欄位可能為 null，不要當作 0。

匯出 Excel 帳單

在匯出帳單的線上測試使用相同條件提交，成功取得檔案後：

核對結果顯示的匯出時間範圍。
保留含時間範圍的檔名，或編輯「檔案名稱」；.xlsx 副檔名會自動保留。
按「下載 Excel 帳單」儲存至本機。

檔名時間使用瀏覽器本地時區。Excel 內容及欄位由平台產生，改名不改內容；核對查詢與匯出時，請使用一致的時間、粒度與名稱條件。

HTTP 200 不保證匯出成功：若回傳 JSON，先處理業務錯誤，不要儲存成 .xlsx。

常見問題

現象	處理方式
成功但沒有記錄	檢查時間單位與範圍，再清空名稱條件
業務 `code: 401`，驗證失敗	檢查存取權杖；有效但仍失敗時聯絡支援
匯出業務 `code: 400`，參數驗證失敗	檢查粒度與開始、結束時間
匯出業務 `code: 500`，`ERROR`	檢查 JSON 及參數型別；正確仍失敗再聯絡管理員
Excel 無法開啟	檢查 Content-Type，確認沒有把 JSON 錯誤存成 Excel

上述匯出業務錯誤可能使用 HTTP 200，不能只依 HTTP 判斷成功。完整範例見對應 Reference。

最新模型價格請至模型廣場查看。

在程式中呼叫

以下 Bash 例子需 curl、jq，涵蓋取得驗證、查詢與儲存 Excel 三步。

依序合併下方三個程式碼區塊至一個 .sh，替換權杖和時間後使用 bash 執行；不要分段貼入互動終端機。

範例為北京時間 2026-10-10 00:00:00 至 2026-10-20 23:59:59，按日統計且不加名稱條件，請改為所需範圍。

1. 取得帳單驗證

用存取權杖呼叫 GET /api/user/self，解析 data.remark 的 token，用於同一網站的帳單請求。存取權杖只用於第一步 Bearer 驗證，不能直接替換帳單的 token Header。

set -euo pipefail

ACCESS_TOKEN='your-user-token'

BILLING_TOKEN=$(curl --fail --silent --show-error "https://api.agtcloud.cn/api/user/self" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | \
  jq -er '
    select(.success == true)
    | .data.remark | fromjson | .token
    | select(type == "string" or type == "number")
    | tostring | select(length > 0)
  ')

2. 查詢統計

curl --fail-with-body "https://api.agtcloud.cn/bill/stats" \
  -X POST \
  -H "token: ${BILLING_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": 3,
    "startTime": 1791561600,
    "endTime": 1792511999
  }'

以 JSON code 判斷業務成功，勿只看 cURL 結束狀態。根層 timestamp 為毫秒，查詢時間為秒。

3. 驗證與儲存 Excel

成功應為 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet 檔案串流，而非 JSON 業務錯誤。

先寫入暫存檔，僅在 HTTP 200、Excel 型別且非空時才儲存為 bill_export.xlsx；不覆蓋既有檔案。

response_file=$(mktemp './.bill_export.XXXXXX')
[[ "$response_file" == ./.bill_export.* && -f "$response_file" && ! -L "$response_file" ]] || exit 1
trap 'if [[ "$response_file" == ./.bill_export.* && -f "$response_file" && ! -L "$response_file" ]]; then rm -f -- "$response_file"; fi' EXIT

response_meta=$(curl --silent --show-error "https://api.agtcloud.cn/bill/excel" \
  -X POST \
  -H "token: ${BILLING_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": 3,
  "startTime": 1791561600,
  "endTime": 1792511999
}' \
  --output "$response_file" \
  --write-out '%{http_code}\n%{content_type}')

http_status=${response_meta%%$'\n'*}
content_type=${response_meta#*$'\n'}
if [[ "$http_status" != 200 || "${content_type%%;*}" != application/vnd.openxmlformats-officedocument.spreadsheetml.sheet || ! -s "$response_file" ]]; then
  printf 'Export failed: HTTP %s (%s)\n' "$http_status" "$content_type" >&2
  if [[ "${content_type%%;*}" == application/json ]]; then
    jq '{code, message}' "$response_file" >&2
  fi
  exit 1
fi

if [[ -e bill_export.xlsx || -L bill_export.xlsx ]]; then
  printf 'bill_export.xlsx already exists; choose another filename.\n' >&2
  exit 1
fi
mv -n -- "$response_file" bill_export.xlsx
if [[ -e "$response_file" ]]; then
  printf 'bill_export.xlsx already exists; choose another filename.\n' >&2
  exit 1
fi
printf 'Saved bill_export.xlsx\n'