使用紀錄與費用
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
/api/v1/usagecurl --fail-with-body "https://ailoot.ai/api/v1/usage" \
-H "Authorization: Bearer $TOKEN"查詢參數
| 欄位 | 類型 | 必填 | 驗證/說明 |
|---|---|---|---|
sort_by | string | 否 | ; 預設值:created_at |
sort_order | string | 否 | ; 預設值:desc |
api_key_id | integer | 否 | |
request_type | string | 否 | |
stream | boolean | 否 | |
timezone | string | 否 | |
start_date | string | 否 | |
end_date | string | 否 | |
period | string | 否 | |
model | string | 否 | |
page | integer | 否 | ; 預設值:1;正數;page_size/limit <=1000 |
page_size | integer | 否 | ; 預設值:20;正數;page_size/limit <=1000 |
limit | integer | 否 | ; 預設值: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
/api/v1/usage/:idcurl --fail-with-body "https://ailoot.ai/api/v1/usage/$ID" \
-H "Authorization: Bearer $TOKEN"路徑參數
| 欄位 | 類型 | 必填 | 驗證/說明 |
|---|---|---|---|
id | integer | 是 |
不需要請求主體。請在 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
/api/v1/usage/dashboard/api-keys-usageJSON/表單欄位
| 欄位 | 類型 | 必填 | 驗證/說明 |
|---|---|---|---|
api_key_ids | array | 是 | 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
/api/v1/usage/dashboard/modelscurl --fail-with-body "https://ailoot.ai/api/v1/usage/dashboard/models" \
-H "Authorization: Bearer $TOKEN"查詢參數
| 欄位 | 類型 | 必填 | 驗證/說明 |
|---|---|---|---|
api_key_id | integer | 否 | |
request_type | string | 否 | |
stream | boolean | 否 | |
timezone | string | 否 | |
start_date | string | 否 | |
end_date | string | 否 | |
period | string | 否 | |
model | string | 否 |
不需要請求主體。請在 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
/api/v1/usage/dashboard/snapshot-v2curl --fail-with-body "https://ailoot.ai/api/v1/usage/dashboard/snapshot-v2" \
-H "Authorization: Bearer $TOKEN"查詢參數
| 欄位 | 類型 | 必填 | 驗證/說明 |
|---|---|---|---|
granularity | string | 否 | ; 預設值:day |
include_trend | boolean | 否 | ; 預設值:true |
include_model_stats | boolean | 否 | ; 預設值:true |
api_key_id | integer | 否 | |
request_type | string | 否 | |
stream | boolean | 否 | |
timezone | string | 否 | |
start_date | string | 否 | |
end_date | string | 否 | |
period | string | 否 | |
model | string | 否 |
不需要請求主體。請在 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
/api/v1/usage/dashboard/statscurl --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
/api/v1/usage/dashboard/trendcurl --fail-with-body "https://ailoot.ai/api/v1/usage/dashboard/trend" \
-H "Authorization: Bearer $TOKEN"查詢參數
| 欄位 | 類型 | 必填 | 驗證/說明 |
|---|---|---|---|
granularity | string | 否 | ; 預設值:day |
api_key_id | integer | 否 | |
request_type | string | 否 | |
stream | boolean | 否 | |
timezone | string | 否 | |
start_date | string | 否 | |
end_date | string | 否 | |
period | string | 否 | |
model | string | 否 |
不需要請求主體。請在 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
/api/v1/usage/errorscurl --fail-with-body "https://ailoot.ai/api/v1/usage/errors" \
-H "Authorization: Bearer $TOKEN"查詢參數
| 欄位 | 類型 | 必填 | 驗證/說明 |
|---|---|---|---|
timezone | string | 否 | |
start_date | string | 否 | |
end_date | string | 否 | |
model | string | 否 | |
api_key_id | integer | 否 | |
status_code | integer | 否 | |
category | string | 否 | |
sort_by | string | 否 | |
sort_order | string | 否 | |
page | integer | 否 | ; 預設值:1;正數;page_size/limit <=1000 |
page_size | integer | 否 | ; 預設值:20;正數;page_size/limit <=1000 |
limit | integer | 否 | ; 預設值: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
/api/v1/usage/errors/:idcurl --fail-with-body "https://ailoot.ai/api/v1/usage/errors/$ID" \
-H "Authorization: Bearer $TOKEN"路徑參數
| 欄位 | 類型 | 必填 | 驗證/說明 |
|---|---|---|---|
id | integer | 是 |
不需要請求主體。請在 URL 中傳入上述參數。
回應
JSON 回應包含 code、message與data。data 的內容請見下方結構描述。
{
"code": 0,
"message": "success",
"data": "PLACEHOLDER_DATA (object, 說明請參閱「資料結構」頁面)"
}注意事項:所有個人資料與物件,皆限於 JWT 主體的範圍。
GET /api/v1/usage/stats —用量統計
存取條件:控制台 token
/api/v1/usage/statscurl --fail-with-body "https://ailoot.ai/api/v1/usage/stats" \
-H "Authorization: Bearer $TOKEN"查詢參數
| 欄位 | 類型 | 必填 | 驗證/說明 |
|---|---|---|---|
api_key_id | integer | 否 | |
request_type | string | 否 | |
stream | boolean | 否 | |
timezone | string | 否 | |
start_date | string | 否 | |
end_date | string | 否 | |
period | string | 否 | |
model | string | 否 |
不需要請求主體。請在 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
/api/v1/user/api-keys/:id/usage/dailycurl --fail-with-body "https://ailoot.ai/api/v1/user/api-keys/$ID/usage/daily" \
-H "Authorization: Bearer $TOKEN"路徑參數
| 欄位 | 類型 | 必填 | 驗證/說明 |
|---|---|---|---|
id | integer | 是 |
查詢參數
| 欄位 | 類型 | 必填 | 驗證/說明 |
|---|---|---|---|
days | integer | 否 | ; 預設值:30 |
timezone | string | 否 |
不需要請求主體。請在 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.