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 在创建任务时就会扣除积分，因此仍在运行中的任务不会出现在记录里。在将记录与你的积分余额核对之前，请再次拉取最近的时间窗口，或稍作延迟后再导出。

如果你的团队设有数据保留期限，则时间窗口的起始时间不会早于该期限所允许的范围。

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 timestamp 格式，例如 2026-08-01T00:00:00Z。记录将包含在此时间或之后创建的任务。留空则时间窗口从 end_time 之前 30 天开始。
时间窗口最长可跨越 366 天。更长的时间窗口将返回 400，因此请将更长的导出拆分为多个时间窗口。
Name
end_time
Type
string
Description
时间窗口的结束时间，采用 RFC 3339 timestamp 格式。记录将包含在此时间之前创建的任务。留空则以你发起请求的时间作为窗口结束时间。
Name
endpoints
Type
string
Description
要包含的 endpoint 列表，以逗号分隔，名称与 endpoint 字段相同。留空则包含所有 endpoint。未知名称将返回 400。
可用值：
- text-to-3d：所有 Text to 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
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。Text to 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 请求头中发送的标签。如果没有，则为 {}。参见Metadata。