Usage API

Usage API 返回团队历史 API 任务及每个任务消耗的 credits。可按时间窗口、endpoint 或状态进行筛选，并可翻页浏览结果以批量导出。

可用性。 API key 必须属于 Studio 或 Enterprise 团队；其他套餐的 API key，或未加入团队的 API key，将收到 403。

GET/openapi/v1/usage/tasks

列出使用记录

返回团队 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。可接受与响应字段 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——其中 text-to-3d 是同时涵盖 preview 与 refine 两个阶段的统称。省略该参数则包含所有 endpoint。

  • Name
    status
    Type
    string
    Description

    按任务的终态进行筛选：SUCCEEDED 或 FAILED。省略该参数则两者都包含。

返回值

返回分页的使用记录对象列表。

记录仅涵盖已达到终态的任务。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"
  }
]

使用记录对象

  • Name
    task_id
    Type
    string
    Description

    该记录所计费任务的 ID——与创建该任务的 endpoint 所返回的 ID 相同。要获取任务本身（包括其输出模型或图片的 URL，该 URL 在每次读取时都会重新签名），可将此 ID 传入对应的获取 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"
}