lowpoly 將於 2026年10月30日 下線。 meshy-7 作為 3D 生成模型將於 2026年12月31日 下線;作為貼圖模型仍可使用。 請在這些日期前切換模型,以免請求出錯。 查看所有棄用資訊

Usage API

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

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


GET/openapi/v1/usage/tasks

列出用量記錄

返回一頁你的團隊的用量記錄,預設按最新優先排序。如果不提供 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

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
    • relief
  • 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 請求頭中發送的標籤。如果沒有則為 {}。參見元資料。