Usage API

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

可用性。 API key 必須屬於 Studio 或 Enterprise 團隊；其他方案的 key，或未加入任何團隊的 key，將收到 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 回應欄位相同的值——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 在任務建立時即被扣除，因此若某任務在你匯出時仍在執行中，它尚不會出現在該時間範圍的結果中——如果你的總數需要與 credits 的餘額精確吻合，請重新拉取最近的時間範圍（或延遲一小段時間後再匯出）。

擁有自訂資料保留政策的團隊，將在其設定的保留期限內收到記錄。

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，每次讀取時都會重新簽署），請將該 ID 傳給對應的取得 endpoint，例如 GET /openapi/v1/{endpoint}/{task_id}。

  • Name
    endpoint
    Type
    string
    Description

    任務執行所在的 endpoint，例如 image-to-3d 或 text-to-3d-refine。Text to 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 key 的顯示名稱。即使 key 已被撤銷，該欄位仍會保留，因此在 key 輪換後歷史支出仍可追溯歸屬。

  • Name
    api_key_suffix
    Type
    string
    Description

    該 API key 的最後四個字元，用於區分名稱相同的 key。

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