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 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
    • 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。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 请求头中发送的标签。如果没有则为 {}。参见元数据。