Usage API

Usage API 回傳團隊歷史 API 任務及每個任務消耗的 credits。可依時間範圍、endpoint 或狀態進行篩選，並可翻頁瀏覽結果以批次匯出。

可用性。 API 金鑰必須屬於 Studio 或 Enterprise 團隊；其他方案的 API 金鑰，或未加入團隊的 API 金鑰，將收到 403。

GET/openapi/v1/usage/tasks

列出使用記錄

回傳團隊 API 任務的一頁記錄，依最新建立時間排列。若未明確指定時間範圍，回應將涵蓋最近 30 天。

參數

  • Name
    page_num
    Type
    integer
    預設值 1
    Description

    分頁的頁碼。

  • Name
    page_size
    Type
    integer
    預設值 10
    Description

    分頁大小限制。允許的最大值為 100 筆。

  • Name
    sort_by
    Type
    string
    預設值 -created_at
    Description

    用於排序的欄位。

    可用的值：

    • +created_at：依建立時間升冪排序。
    • -created_at：依建立時間降冪排序。
  • Name
    start_time
    Type
    string
    Description

    created_at 範圍的起始時間，採用 RFC 3339 時間戳格式（例如 2026-08-01T00:00:00Z）。預設為 end_time 之前 30 天。該範圍跨度最長不超過 1 年——如需匯出更大範圍的資料，請分段翻頁取得連續的時間範圍。

  • Name
    end_time
    Type
    string
    Description

    created_at 範圍的結束時間，採用 RFC 3339 時間戳格式。預設為目前時間。

  • Name
    endpoints
    Type
    string
    Description

    以逗號分隔的 endpoint 名稱清單，用於指定要包含的 endpoint。可接受與回應欄位 endpoint 相同的值——text-to-3d、text-to-3d-preview、text-to-3d-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——其中 text-to-3d 是同時涵蓋 preview 與 refine 兩個階段的統稱。省略此參數則包含所有 endpoint。

  • Name
    status
    Type
    string
    Description

    依任務的最終狀態進行篩選：SUCCEEDED 或 FAILED。省略此參數則兩者皆包含。

回傳值

回傳分頁的使用記錄物件清單。

記錄僅涵蓋已達到最終狀態的任務。credits 會在任務建立時扣除，因此在你匯出資料時仍在執行中的任務尚不會出現在該時間範圍的結果中——如果你的總數需要與 credit 餘額精確吻合，請重新拉取最近的時間範圍（或延遲一段時間後再匯出）。

擁有自訂資料保留政策的團隊，可在其設定的保留範圍內取得記錄。

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"
  },
  {
    "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"
  }
]

使用記錄物件

  • Name
    task_id
    Type
    string
    Description

    該記錄所計費任務的 ID——與建立該任務的 endpoint 所回傳的 ID 相同。要取得任務本身（包括其輸出模型或圖片的 URL，該 URL 在每次讀取時都會重新簽署），可將此 ID 傳入對應的取得 endpoint，例如 GET /openapi/v1/{endpoint}/{task_id}。

  • Name
    endpoint
    Type
    string
    Description

    該任務所執行的 endpoint，例如 image-to-3d 或 text-to-3d-refine。文字生成 3D 任務會回報其所處階段（text-to-3d-preview / text-to-3d-refine）。

  • Name
    status
    Type
    string
    Description

    任務的最終狀態：SUCCEEDED 或 FAILED。

  • Name
    created_at
    Type
    timestamp
    Description

    任務建立的時間戳，單位為毫秒。

  • Name
    finished_at
    Type
    timestamp
    Description

    任務完成的時間戳，單位為毫秒。若該任務沒有完成時間，則為 null。

  • Name
    consumed_credits
    Type
    integer
    Description

    該任務消耗的 credits。對於 FAILED 任務回傳 0（失敗時 credits 會被退還）。

  • Name
    api_key_name
    Type
    string
    Description

    執行該任務的 API 金鑰的顯示名稱。即使該金鑰已被吊銷，此欄位仍會保留，因此在金鑰輪替後，歷史支出仍可追溯歸屬。

  • Name
    api_key_suffix
    Type
    string
    Description

    該 API 金鑰的最後四個字元，用於區分同名的不同金鑰。

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"
}