文件
控制台 API

使用紀錄與費用

Markdown

方法、請求欄位與回應。

完整指南

本區共有 11 個方法。開啟方法即可查看存取條件、請求欄位與回應。

方法與路徑說明存取條件
GET /api/v1/usage請求歷史紀錄控制台 token
GET /api/v1/usage/:id歷史紀錄中的單一請求控制台 token
POST /api/v1/usage/dashboard/api-keys-usage自己 API 金鑰的統計資料控制台 token
GET /api/v1/usage/dashboard/models依模型分類的用量控制台 token
GET /api/v1/usage/dashboard/snapshot-v2圖表的統一快照控制台 token
GET /api/v1/usage/dashboard/stats用量摘要控制台 token
GET /api/v1/usage/dashboard/trend用量變化趨勢控制台 token
GET /api/v1/usage/errors錯誤歷史紀錄控制台 token
GET /api/v1/usage/errors/:id自己發生的錯誤之詳細資訊控制台 token
GET /api/v1/usage/stats用量統計控制台 token
GET /api/v1/user/api-keys/:id/usage/daily自己 API 金鑰的每日統計資料控制台 token
GET /api/v1/usage —請求歷史紀錄

存取條件:控制台 token

GET/api/v1/usage
讀取;ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/usage" \
  -H "Authorization: Bearer $TOKEN"

查詢參數

欄位類型必填驗證/說明
sort_bystring否; 預設值:created_at
sort_orderstring否; 預設值:desc
api_key_idinteger否
request_typestring否
streamboolean否
timezonestring否
start_datestring否
end_datestring否
periodstring否
modelstring否
pageinteger否; 預設值:1;正數;page_size/limit <=1000
page_sizeinteger否; 預設值:20;正數;page_size/limit <=1000
limitinteger否; 預設值:20;正數;page_size/limit <=1000

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應資料的結構描述:UsageLog。欄位與型別請見「資料結構描述」頁面。

回應結構描述,欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "PLACEHOLDER_ID (integer)",
        "user_id": "PLACEHOLDER_USER_ID (integer)",
        "api_key_id": "PLACEHOLDER_API_KEY_ID (integer)",
        "request_id": "PLACEHOLDER_REQUEST_ID (string)",
        "model": "PLACEHOLDER_MODEL (string)",
        "service_tier": "PLACEHOLDER_SERVICE_TIER (string)",
        "reasoning_effort": "PLACEHOLDER_REASONING_EFFORT (string)",
        "input_tokens": "PLACEHOLDER_INPUT_TOKENS (integer)",
        "output_tokens": "PLACEHOLDER_OUTPUT_TOKENS (integer)",
        "cache_creation_tokens": "PLACEHOLDER_CACHE_CREATION_TOKENS (integer)",
        "cache_read_tokens": "PLACEHOLDER_CACHE_READ_TOKENS (integer)",
        "cache_creation_5m_tokens": "PLACEHOLDER_CACHE_CREATION_5M_TOKENS (integer)",
        "cache_creation_1h_tokens": "PLACEHOLDER_CACHE_CREATION_1H_TOKENS (integer)",
        "input_cost": "PLACEHOLDER_INPUT_COST (number)",
        "output_cost": "PLACEHOLDER_OUTPUT_COST (number)",
        "cache_creation_cost": "PLACEHOLDER_CACHE_CREATION_COST (number)",
        "cache_read_cost": "PLACEHOLDER_CACHE_READ_COST (number)",
        "total_cost": "PLACEHOLDER_TOTAL_COST (number)",
        "actual_cost": "PLACEHOLDER_ACTUAL_COST (number)",
        "long_context_billing_applied": "PLACEHOLDER_LONG_CONTEXT_BILLING_APPLIED (boolean)",
        "request_type": "PLACEHOLDER_REQUEST_TYPE (string)",
        "stream": "PLACEHOLDER_STREAM (boolean)",
        "duration_ms": "PLACEHOLDER_DURATION_MS (integer)",
        "first_token_ms": "PLACEHOLDER_FIRST_TOKEN_MS (integer)",
        "image_count": "PLACEHOLDER_IMAGE_COUNT (integer)",
        "image_size": "PLACEHOLDER_IMAGE_SIZE (string)",
        "image_input_size": "PLACEHOLDER_IMAGE_INPUT_SIZE (string)",
        "image_output_size": "PLACEHOLDER_IMAGE_OUTPUT_SIZE (string)",
        "image_input_tokens": "PLACEHOLDER_IMAGE_INPUT_TOKENS (integer)",
        "image_input_cost": "PLACEHOLDER_IMAGE_INPUT_COST (number)",
        "image_output_tokens": "PLACEHOLDER_IMAGE_OUTPUT_TOKENS (integer)",
        "image_output_cost": "PLACEHOLDER_IMAGE_OUTPUT_COST (number)",
        "image_size_breakdown": "PLACEHOLDER_IMAGE_SIZE_BREAKDOWN (object)",
        "media_type": "PLACEHOLDER_MEDIA_TYPE (string)",
        "ip_address": "PLACEHOLDER_IP_ADDRESS (string)",
        "session_id": "PLACEHOLDER_SESSION_ID (string)",
        "created_at": "PLACEHOLDER_CREATED_AT (string)",
        "user": "PLACEHOLDER_USER (object)",
        "api_key": "PLACEHOLDER_API_KEY (object)"
      }
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}

注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。

GET /api/v1/usage/:id —歷史紀錄中的單一請求

存取條件:控制台 token

GET/api/v1/usage/:id
讀取;ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/usage/$ID" \
  -H "Authorization: Bearer $TOKEN"

路徑參數

欄位類型必填驗證/說明
idinteger是

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應資料的結構描述:UsageLog。欄位與型別請見「資料結構描述」頁面。

回應結構描述,欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "api_key_id": "PLACEHOLDER_API_KEY_ID (integer)",
    "request_id": "PLACEHOLDER_REQUEST_ID (string)",
    "model": "PLACEHOLDER_MODEL (string)",
    "service_tier": "PLACEHOLDER_SERVICE_TIER (string)",
    "reasoning_effort": "PLACEHOLDER_REASONING_EFFORT (string)",
    "input_tokens": "PLACEHOLDER_INPUT_TOKENS (integer)",
    "output_tokens": "PLACEHOLDER_OUTPUT_TOKENS (integer)",
    "cache_creation_tokens": "PLACEHOLDER_CACHE_CREATION_TOKENS (integer)",
    "cache_read_tokens": "PLACEHOLDER_CACHE_READ_TOKENS (integer)",
    "cache_creation_5m_tokens": "PLACEHOLDER_CACHE_CREATION_5M_TOKENS (integer)",
    "cache_creation_1h_tokens": "PLACEHOLDER_CACHE_CREATION_1H_TOKENS (integer)",
    "input_cost": "PLACEHOLDER_INPUT_COST (number)",
    "output_cost": "PLACEHOLDER_OUTPUT_COST (number)",
    "cache_creation_cost": "PLACEHOLDER_CACHE_CREATION_COST (number)",
    "cache_read_cost": "PLACEHOLDER_CACHE_READ_COST (number)",
    "total_cost": "PLACEHOLDER_TOTAL_COST (number)",
    "actual_cost": "PLACEHOLDER_ACTUAL_COST (number)",
    "long_context_billing_applied": "PLACEHOLDER_LONG_CONTEXT_BILLING_APPLIED (boolean)",
    "request_type": "PLACEHOLDER_REQUEST_TYPE (string)",
    "stream": "PLACEHOLDER_STREAM (boolean)",
    "duration_ms": "PLACEHOLDER_DURATION_MS (integer)",
    "first_token_ms": "PLACEHOLDER_FIRST_TOKEN_MS (integer)",
    "image_count": "PLACEHOLDER_IMAGE_COUNT (integer)",
    "image_size": "PLACEHOLDER_IMAGE_SIZE (string)",
    "image_input_size": "PLACEHOLDER_IMAGE_INPUT_SIZE (string)",
    "image_output_size": "PLACEHOLDER_IMAGE_OUTPUT_SIZE (string)",
    "image_input_tokens": "PLACEHOLDER_IMAGE_INPUT_TOKENS (integer)",
    "image_input_cost": "PLACEHOLDER_IMAGE_INPUT_COST (number)",
    "image_output_tokens": "PLACEHOLDER_IMAGE_OUTPUT_TOKENS (integer)",
    "image_output_cost": "PLACEHOLDER_IMAGE_OUTPUT_COST (number)",
    "image_size_breakdown": "PLACEHOLDER_IMAGE_SIZE_BREAKDOWN (object)",
    "media_type": "PLACEHOLDER_MEDIA_TYPE (string)",
    "ip_address": "PLACEHOLDER_IP_ADDRESS (string)",
    "session_id": "PLACEHOLDER_SESSION_ID (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "user": "PLACEHOLDER_USER (object)",
    "api_key": "PLACEHOLDER_API_KEY (object)"
  }
}

注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。

POST /api/v1/usage/dashboard/api-keys-usage —自己 API 金鑰的統計資料

存取條件:控制台 token

POST/api/v1/usage/dashboard/api-keys-usage

JSON/表單欄位

欄位類型必填驗證/說明
api_key_idsarray是required
請求主體範本
{
  "api_key_ids": "PLACEHOLDER_API_KEY_IDS (array)"
}

PLACEHOLDER 表示您的輸入及其型別。請替換值,並只保留需要的選填欄位;不要將字串標記當成數字、boolean、物件或陣列傳送。

請求結構描述:BatchAPIKeysUsageRequest

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應資料的結構描述:BatchAPIKeyUsageStats。欄位與型別請見「資料結構描述」頁面。

回應結構描述,欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "api_key_id": "PLACEHOLDER_API_KEY_ID (integer)",
    "today_actual_cost": "PLACEHOLDER_TODAY_ACTUAL_COST (number)",
    "total_actual_cost": "PLACEHOLDER_TOTAL_ACTUAL_COST (number)"
  }
}

注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。

特性:此方法會讀取您自有 API 金鑰的統計資料;範例僅描述 API 契約,不會執行。

GET /api/v1/usage/dashboard/models —依模型分類的用量

存取條件:控制台 token

GET/api/v1/usage/dashboard/models
讀取;ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/usage/dashboard/models" \
  -H "Authorization: Bearer $TOKEN"

查詢參數

欄位類型必填驗證/說明
api_key_idinteger否
request_typestring否
streamboolean否
timezonestring否
start_datestring否
end_datestring否
periodstring否
modelstring否

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應結構描述,欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "end_date": "VALUE_FROM_RESPONSE",
    "models": "VALUE_FROM_RESPONSE",
    "month": "VALUE_FROM_RESPONSE",
    "start_date": "VALUE_FROM_RESPONSE",
    "today": "VALUE_FROM_RESPONSE",
    "week": "VALUE_FROM_RESPONSE"
  }
}

注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。

GET /api/v1/usage/dashboard/snapshot-v2 —圖表的統一快照

存取條件:控制台 token

GET/api/v1/usage/dashboard/snapshot-v2
讀取;ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/usage/dashboard/snapshot-v2" \
  -H "Authorization: Bearer $TOKEN"

查詢參數

欄位類型必填驗證/說明
granularitystring否; 預設值:day
include_trendboolean否; 預設值:true
include_model_statsboolean否; 預設值:true
api_key_idinteger否
request_typestring否
streamboolean否
timezonestring否
start_datestring否
end_datestring否
periodstring否
modelstring否

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應結構描述,欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "end_date": "VALUE_FROM_RESPONSE",
    "generated_at": "VALUE_FROM_RESPONSE",
    "granularity": "VALUE_FROM_RESPONSE",
    "month": "VALUE_FROM_RESPONSE",
    "start_date": "VALUE_FROM_RESPONSE",
    "today": "VALUE_FROM_RESPONSE",
    "week": "VALUE_FROM_RESPONSE"
  }
}

注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。

GET /api/v1/usage/dashboard/stats —用量摘要

存取條件:控制台 token

GET/api/v1/usage/dashboard/stats
讀取;ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/usage/dashboard/stats" \
  -H "Authorization: Bearer $TOKEN"

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應資料的結構描述:UserDashboardStats。欄位與型別請見「資料結構描述」頁面。

回應結構描述,欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "total_api_keys": "PLACEHOLDER_TOTAL_API_KEYS (integer)",
    "active_api_keys": "PLACEHOLDER_ACTIVE_API_KEYS (integer)",
    "total_requests": "PLACEHOLDER_TOTAL_REQUESTS (integer)",
    "total_input_tokens": "PLACEHOLDER_TOTAL_INPUT_TOKENS (integer)",
    "total_output_tokens": "PLACEHOLDER_TOTAL_OUTPUT_TOKENS (integer)",
    "total_cache_creation_tokens": "PLACEHOLDER_TOTAL_CACHE_CREATION_TOKENS (integer)",
    "total_cache_read_tokens": "PLACEHOLDER_TOTAL_CACHE_READ_TOKENS (integer)",
    "total_tokens": "PLACEHOLDER_TOTAL_TOKENS (integer)",
    "total_cost": "PLACEHOLDER_TOTAL_COST (number)",
    "total_actual_cost": "PLACEHOLDER_TOTAL_ACTUAL_COST (number)",
    "today_requests": "PLACEHOLDER_TODAY_REQUESTS (integer)",
    "today_input_tokens": "PLACEHOLDER_TODAY_INPUT_TOKENS (integer)",
    "today_output_tokens": "PLACEHOLDER_TODAY_OUTPUT_TOKENS (integer)",
    "today_cache_creation_tokens": "PLACEHOLDER_TODAY_CACHE_CREATION_TOKENS (integer)",
    "today_cache_read_tokens": "PLACEHOLDER_TODAY_CACHE_READ_TOKENS (integer)",
    "today_tokens": "PLACEHOLDER_TODAY_TOKENS (integer)",
    "today_cost": "PLACEHOLDER_TODAY_COST (number)",
    "today_actual_cost": "PLACEHOLDER_TODAY_ACTUAL_COST (number)",
    "average_duration_ms": "PLACEHOLDER_AVERAGE_DURATION_MS (number)",
    "rpm": "PLACEHOLDER_RPM (integer)",
    "tpm": "PLACEHOLDER_TPM (integer)"
  }
}

注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。

GET /api/v1/usage/dashboard/trend —用量變化趨勢

存取條件:控制台 token

GET/api/v1/usage/dashboard/trend
讀取;ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/usage/dashboard/trend" \
  -H "Authorization: Bearer $TOKEN"

查詢參數

欄位類型必填驗證/說明
granularitystring否; 預設值:day
api_key_idinteger否
request_typestring否
streamboolean否
timezonestring否
start_datestring否
end_datestring否
periodstring否
modelstring否

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應結構描述,欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "end_date": "VALUE_FROM_RESPONSE",
    "granularity": "VALUE_FROM_RESPONSE",
    "month": "VALUE_FROM_RESPONSE",
    "start_date": "VALUE_FROM_RESPONSE",
    "today": "VALUE_FROM_RESPONSE",
    "trend": "VALUE_FROM_RESPONSE",
    "week": "VALUE_FROM_RESPONSE"
  }
}

注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。

GET /api/v1/usage/errors —錯誤歷史紀錄

存取條件:控制台 token

GET/api/v1/usage/errors
讀取;ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/usage/errors" \
  -H "Authorization: Bearer $TOKEN"

查詢參數

欄位類型必填驗證/說明
timezonestring否
start_datestring否
end_datestring否
modelstring否
api_key_idinteger否
status_codeinteger否
categorystring否
sort_bystring否
sort_orderstring否
pageinteger否; 預設值:1;正數;page_size/limit <=1000
page_sizeinteger否; 預設值:20;正數;page_size/limit <=1000
limitinteger否; 預設值:20;正數;page_size/limit <=1000

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應結構描述,欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      "PLACEHOLDER_DATA (object, 說明請參閱「資料結構」頁面)"
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}

注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。

GET /api/v1/usage/errors/:id —自己發生的錯誤之詳細資訊

存取條件:控制台 token

GET/api/v1/usage/errors/:id
讀取;ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/usage/errors/$ID" \
  -H "Authorization: Bearer $TOKEN"

路徑參數

欄位類型必填驗證/說明
idinteger是

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應結構描述,欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": "PLACEHOLDER_DATA (object, 說明請參閱「資料結構」頁面)"
}

注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。

GET /api/v1/usage/stats —用量統計

存取條件:控制台 token

GET/api/v1/usage/stats
讀取;ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/usage/stats" \
  -H "Authorization: Bearer $TOKEN"

查詢參數

欄位類型必填驗證/說明
api_key_idinteger否
request_typestring否
streamboolean否
timezonestring否
start_datestring否
end_datestring否
periodstring否
modelstring否

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應資料的結構描述:UsageStats。欄位與型別請見「資料結構描述」頁面。

回應結構描述,欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "total_requests": "PLACEHOLDER_TOTAL_REQUESTS (integer)",
    "total_input_tokens": "PLACEHOLDER_TOTAL_INPUT_TOKENS (integer)",
    "total_output_tokens": "PLACEHOLDER_TOTAL_OUTPUT_TOKENS (integer)",
    "total_cache_tokens": "PLACEHOLDER_TOTAL_CACHE_TOKENS (integer)",
    "total_cache_creation_tokens": "PLACEHOLDER_TOTAL_CACHE_CREATION_TOKENS (integer)",
    "total_cache_read_tokens": "PLACEHOLDER_TOTAL_CACHE_READ_TOKENS (integer)",
    "total_tokens": "PLACEHOLDER_TOTAL_TOKENS (integer)",
    "total_cost": "PLACEHOLDER_TOTAL_COST (number)",
    "total_actual_cost": "PLACEHOLDER_TOTAL_ACTUAL_COST (number)",
    "average_duration_ms": "PLACEHOLDER_AVERAGE_DURATION_MS (number)",
    "endpoints": "PLACEHOLDER_ENDPOINTS (array)"
  }
}

注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。

GET /api/v1/user/api-keys/:id/usage/daily —自己 API 金鑰的每日統計資料

存取條件:控制台 token

GET/api/v1/user/api-keys/:id/usage/daily
讀取;ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/user/api-keys/$ID/usage/daily" \
  -H "Authorization: Bearer $TOKEN"

路徑參數

欄位類型必填驗證/說明
idinteger是

查詢參數

欄位類型必填驗證/說明
daysinteger否; 預設值:30
timezonestring否

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應資料的結構描述:APIKeyDailyUsagePoint。欄位與型別請見「資料結構描述」頁面。

回應結構描述,欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "date": "PLACEHOLDER_DATE (string)",
    "requests": "PLACEHOLDER_REQUESTS (integer)",
    "input_tokens": "PLACEHOLDER_INPUT_TOKENS (integer)",
    "output_tokens": "PLACEHOLDER_OUTPUT_TOKENS (integer)",
    "cache_read_tokens": "PLACEHOLDER_CACHE_READ_TOKENS (integer)",
    "cache_write_tokens": "PLACEHOLDER_CACHE_WRITE_TOKENS (integer)",
    "total_tokens": "PLACEHOLDER_TOTAL_TOKENS (integer)",
    "cost": "PLACEHOLDER_COST (number)",
    "actual_cost": "PLACEHOLDER_ACTUAL_COST (number)"
  }
}

注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。

使用紀錄與費用 · USD

total_cost 是按費率計算的費用;actual_cost 是記錄的扣款金額,單位為 USD。

計算範例

{
  "total_cost": 0.1,
  "actual_cost": 0.08
}

period ∈ {today, week, month}; start_date, end_date: YYYY-MM-DD; timezone: IANA · timezone=UTC. end_date: [00:00, +1 day 00:00). display: actual_cost.toFixed(8); JSON: number.

還有疑問嗎?請提供 Request ID與問題描述,我們會協助釐清。聯絡支援