按模型統計用量

GET /api/open/v1/usage/models

請求參數

參數	位置	類型	必填	預設值	說明
start_timestamp	query	integer	否	見說明	起始時間（含），unix 秒
end_timestamp	query	integer	否	見說明	結束時間（含），unix 秒
limit	query	integer	否	10	回傳的模型數量，取值 1–100，超出範圍回傳 400

時間範圍規則：

• 兩端都省略：最近 30 天。
• 只傳 start_timestamp：向後 30 天，且不超過目前時間。
• 只傳 end_timestamp：向前 30 天。
• 範圍最長 366 天。

請求範例

curl "https://www.routeapi.ai/api/open/v1/usage/models?start_timestamp=1726400000&end_timestamp=1729000000&limit=10" \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY"

回應範例

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "model_name": "gpt-4o",
        "prompt_tokens": 120000,
        "completion_tokens": 30000,
        "total_tokens": 150000,
        "amount": 3.20
      }
    ],
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

回應欄位

欄位	類型	說明
items[].model_name	string	模型名稱
items[].prompt_tokens	integer	該模型在時間範圍內的輸入 token 總數
items[].completion_tokens	integer	該模型在時間範圍內的輸出 token 總數
items[].total_tokens	integer	輸入與輸出 token 合計
items[].amount	number	該模型消耗的金額，站點幣別，兩位小數
start_timestamp	integer	實際生效的起始時間
end_timestamp	integer	實際生效的結束時間

錯誤

HTTP	code	情境
400	invalid_request	limit 不是 1–100 的整數、時間戳為負數，或時間範圍不合法
429	—	超過按使用者的查詢頻率限制（預設 30 次/分鐘），回應主體可能為空

其他通用錯誤碼見 開放平台 API 錯誤。

說明

• 結果按 total_tokens 倒序；用量相同時按模型名稱升序，順序穩定。
• 只統計消費（計費）日誌，失敗請求不計入。
• token 數為原始計數，不是百萬單位。
• 金額使用站點顯示幣別，見 查詢餘額。
• 每行 amount 獨立四捨五入，各行相加與總量可能相差 ±0.01。
• 本介面與 用量統計、帳戶日誌、匯出日誌、按 Key 統計 共用按使用者的查詢頻率限制（預設 30 次/分鐘），見 頻率限制。