Usage API
列出你的團隊已完成的 API 任務及每個任務消耗的積分,用於帳單匯出與成本報告。
要呼叫此 endpoint,請使用 Studio 或 Enterprise 團隊中活躍成員的 API key。任何成員都可以呼叫它,不僅限於擁有者和管理員。使用其他任何 API key,請求將返回 403。
列出用量記錄
返回一頁你的團隊的用量記錄,預設按最新優先排序。如果不提供 start_time 和 end_time,記錄將涵蓋最近 30 天。呼叫此 endpoint 是免費的。
記錄包含以下任務:
- 以
SUCCEEDED或FAILED結束的 API 任務 - 團隊中每個當前成員的任務,來自其任意 API key
- 你已刪除的任務,以及檔案已過期的任務
記錄不包含以下任務:
- 仍處於
PENDING或IN_PROGRESS狀態的任務,以及CANCELED的任務 - 已離開團隊的人員的任務
- Creative Lab 任務
- Meshy 的 AI 代理執行的任務
- 在 Meshy Web App 中完成的工作
任務只有在完成後才會出現在記錄中,出現在其 created_at 所在的窗口內。Meshy 在建立任務時就會扣除積分,因此仍在執行中的任務不會出現在記錄中。在將記錄與你的積分 Balance 進行核對之前,請重新拉取近期窗口,或延遲一段時間後再匯出。
如果你的團隊設有資料保留期限,窗口的起始時間不會早於該期限所允許的範圍。
Request
curl "https://api.meshy.ai/openapi/v1/usage/tasks?page_size=50&start_time=2026-08-01T00:00:00Z&end_time=2026-09-01T00:00:00Z" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"endpoint": "image-to-3d",
"status": "SUCCEEDED",
"created_at": 1755787000000,
"finished_at": 1755787045000,
"consumed_credits": 20,
"api_key_name": "production",
"api_key_suffix": "a1b2",
"metadata": {
"user": "alex@example.com",
"team": "fab"
}
},
{
"task_id": "018a210d-1c22-7e0f-9d3a-4a5b6c7d8e9f",
"endpoint": "text-to-3d-refine",
"status": "FAILED",
"created_at": 1755786000000,
"finished_at": 1755786030000,
"consumed_credits": 0,
"api_key_name": "production",
"api_key_suffix": "a1b2",
"metadata": {}
}
]
參數
- Name
- page_num
- Type
- integer
- 預設值 1
- Description
要返回的頁碼,範圍從
1到255。超過255的值將返回400。一個窗口最多容納 255 頁,因此請將大型匯出拆分為更短的窗口。
- Name
- page_size
- Type
- integer
- 預設值 10
- Description
每頁的記錄數,範圍從
1到100。101到255之間的值將返回 100 條記錄,超過255的值將返回400。
- Name
- sort_by
- Type
- string
- 預設值 -created_at
- Description
排序順序。
可用值:
+created_at:最舊優先-created_at:最新優先
在 URL 中,請將
+寫為%2B。否則+會被解析為空格,請求將返回400。
- Name
- start_time
- Type
- string
- Description
窗口的起始時間,採用 RFC 3339 時間戳格式,例如
2026-08-01T00:00:00Z。記錄將包含在此時間或之後建立的任務。不提供時,窗口將從end_time之前 30 天開始。窗口最長可跨度 366 天。更長的窗口將返回
400,因此請將更長的匯出拆分為多個窗口。
- Name
- end_time
- Type
- string
- Description
窗口的結束時間,採用 RFC 3339 時間戳格式。記錄將包含在此時間之前建立的任務。不提供時,窗口將以你發出請求的時間結束。
- Name
- endpoints
- Type
- string
- Description
要包含的 endpoint 清單,以逗號分隔,名稱與
endpoint欄位相同。不提供時將包含所有 endpoint。未知名稱將返回400。可用值:
text-to-3d:所有 文字生成 3D 任務,包括 preview 和 refinetext-to-3d-preview:僅 preview 任務text-to-3d-refine:僅 refine 任務image-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
要包含的狀態,
SUCCEEDED或FAILED。不提供時將包含兩者。其他任何值都將返回400。
返回值
返回一個用量記錄陣列。當沒有符合的記錄時,陣列為空。
失敗情況
- Name
400 - Bad Request- Description
某個參數無效,錯誤訊息會說明具體是哪一個。修正該參數後,重新發送請求。
- Name
401 - Unauthorized- Description
API key 缺失或無效。請檢查
Authorization請求頭。
- Name
403 - Forbidden- Description
該 API key 對應的帳戶不是 Studio 或 Enterprise 團隊的活躍成員。訊息為
This endpoint is available on Studio and Enterprise plans。請使用 Studio 或 Enterprise 團隊成員的 API key。
- Name
429 - Too Many Requests- Description
你發送的請求過多。請等待
Retry-After中指定的秒數後再重試。
用量記錄物件
Example usage record object
{
"task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"endpoint": "image-to-3d",
"status": "SUCCEEDED",
"created_at": 1755787000000,
"finished_at": 1755787045000,
"consumed_credits": 20,
"api_key_name": "production",
"api_key_suffix": "a1b2",
"metadata": {
"user": "alex@example.com",
"team": "fab"
}
}
- Name
- task_id
- Type
- string
- Description
任務 ID,與建立該任務的 endpoint 所返回的 ID 相同。要取得任務本身及其輸出 URL,請將該 ID 發送到對應 endpoint 的取得路由,例如對於
image-to-3d記錄,使用GET /openapi/v1/image-to-3d/{task_id}。
- Name
- endpoint
- Type
- string
- Description
任務執行所在的 endpoint,例如
image-to-3d或rig。文字生成 3D 任務會顯示其所處階段,text-to-3d-preview或text-to-3d-refine。較舊的記錄可能帶有已停用 endpoint 的名稱,這些名稱無法被
endpoints過濾參數接受。
- Name
- status
- Type
- string
- Description
任務的最終狀態,
SUCCEEDED或FAILED。
- Name
- created_at
- Type
- timestamp
- Description
任務建立的時間,以 Unix 毫秒數表示。
- Name
- finished_at
- Type
- timestamp
- Description
任務完成的時間,以 Unix 毫秒數表示。如果任務沒有完成時間,則為
null。
- Name
- consumed_credits
- Type
- integer
- Description
任務消耗的積分數,為退款後的淨值。失敗的任務為
0,因為 Meshy 會為其退款;免費任務(如可列印性分析)同樣為0。
- Name
- api_key_name
- Type
- string
- Description
執行該任務的 API key 的名稱。對於透過應用程式登入方式執行的任務,這裡是該應用程式的名稱,例如
Meshy CLI。在某些情況下為空字串,例如:
- 該任務從未被計費,例如可列印性分析任務,它是免費的。
- 該 API key 已被刪除。
- 該 API key 是在最近幾分鐘內建立的。
- Name
- api_key_suffix
- Type
- string
- Description
該 API key 的最後四個字元,用於區分同名的 key。當
api_key_name為空時,以及對於 Meshy CLI 等應用程式登入方式,該欄位為空字串。
- Name
- metadata
- Type
- object
- Description
任務建立時在
X-Meshy-Metadata請求頭中發送的標籤。如果沒有則為{}。參見元資料。