Usage API

列出你團隊已完成的 API 任務及每個任務消耗的積分，用於帳單匯出和成本報告。

要呼叫此 endpoint，請使用 Studio 或 Enterprise 團隊中活躍成員的 API 金鑰。任何成員都可以呼叫，不僅限於擁有者和管理員。使用其他任何 API 金鑰，請求將返回 403。

GET/openapi/v1/usage/tasks

列出用量記錄

返回你團隊用量記錄的一頁內容，預設按最新優先排序。如果未指定 start_time 和 end_time，記錄將涵蓋過去 30 天。呼叫此 endpoint 是免費的。

記錄包含以下任務：

以 SUCCEEDED 或 FAILED 完成的 API 任務
團隊中每位目前成員的任務，無論來自他們的哪個 API 金鑰
你已刪除的任務，以及檔案已過期的任務

記錄不包含以下任務：

仍處於 PENDING 或 IN_PROGRESS 狀態的任務，以及 CANCELED 任務
已離開團隊的人員的任務
Creative Lab 任務
Meshy 的 AI 智慧代理執行的任務
在 Meshy Web App 中完成的工作

任務只有在完成後，才會出現在其 created_at 所在的時間窗口的記錄中。Meshy 在建立任務時就會扣除積分，因此仍在執行中的任務不會出現在記錄裡。在將記錄與你的積分餘額核對之前，請再次拉取最近的時間窗口，或稍作延遲後再匯出。

如果你的團隊設有資料保留期限，則時間窗口的起始時間不會早於該期限所允許的範圍。

Request

GET

/openapi/v1/usage/tasks

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 和 refine
- text-to-3d-preview：僅 preview 任務
- text-to-3d-refine：僅 refine 任務
- image-to-3d
- multi-image-to-3d
- retexture
- remesh
- convert
- resize
- uv-unwrap
- rig
- animate
- text-to-motion
- text-to-image
- image-to-image
- print-multi-color
- print-repair
- print-analyze
- print-split
Name
status
Type
string
Description
要包含的狀態，SUCCEEDED 或 FAILED。留空則兩者都包含。其他任何值都將返回 400。

返回值

返回一個用量記錄陣列。如果沒有符合的記錄，陣列為空。

失敗情形

Name
400 - Bad Request
Description
某個參數無效，錯誤訊息會說明是哪一個。修正該參數後重新發送請求。
Name
401 - Unauthorized
Description
API 金鑰缺失或無效。請檢查 Authorization 請求標頭。
Name
403 - Forbidden
Description
該 API 金鑰所屬帳戶不是 Studio 或 Enterprise 團隊的活躍成員。錯誤訊息為 This endpoint is available on Studio and Enterprise plans。請使用 Studio 或 Enterprise 團隊成員的 API 金鑰。
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 金鑰的名稱。對於透過應用程式登入方式執行的任務，這裡是該應用程式的名稱，例如 Meshy CLI。
在某些情況下該值為空字串，例如：
- 該任務從未被計費，例如免費的可列印性分析任務。
- 該 API 金鑰已被刪除。
- 該 API 金鑰是在最近幾分鐘內建立的。
Name
api_key_suffix
Type
string
Description
該 API 金鑰的最後四個字元，用於區分名稱相同的金鑰。當 api_key_name 為空時，以及對於 Meshy CLI 等應用程式登入方式，該值均為空字串。
Name
metadata
Type
object
Description
任務建立時在 X-Meshy-Metadata 請求標頭中發送的標籤。如果沒有，則為 {}。參見Metadata。