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