Usage API

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

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

GET/openapi/v1/usage/tasks

List Usage Records

回傳團隊 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 timestamp 格式（例如 2026-08-01T00:00:00Z）。預設為 end_time 之前 30 天。該窗口最長可跨 1 年——如需匯出更大範圍，請對連續窗口分頁取得。

  • Name
    end_time
    Type
    string
    Description

    created_at 窗口的結束時間，採用 RFC 3339 timestamp 格式。預設為目前時間。

  • 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、print-split——其中 text-to-3d 是涵蓋 preview 和 refine 兩個階段的統稱。省略該參數則包含所有 endpoint。

  • Name
    status
    Type
    string
    Description

    按任務的最終狀態篩選：SUCCEEDED 或 FAILED。省略該參數則兩者都包含。

回傳值

回傳 Usage Record 物件 的分頁清單。

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

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

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

The Usage Record Object

  • Name
    task_id
    Type
    string
    Description

    該記錄所計費任務的 ID——與建立該任務的 endpoint 所回傳的 ID 相同。要取得任務本身（包括其輸出模型或圖片 URL，每次讀取都會重新簽名），可將其傳給對應的取得 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

    任務建立的 timestamp，單位為毫秒。

  • Name
    finished_at
    Type
    timestamp
    Description

    任務完成的 timestamp，單位為毫秒。如果任務沒有完成時間，則為 null。

  • Name
    consumed_credits
    Type
    integer
    Description

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

  • Name
    api_key_name
    Type
    string
    Description

    執行該任務的 API 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"
}