Usage API
列出你的团队已完成的 API 任务及每个任务消耗的积分,用于账单导出和成本报告。
要调用此 endpoint,请使用 Studio 或 Enterprise 团队中活跃成员的 API key。任何成员都可以调用它,不仅限于所有者和管理员。使用其他任何 API key,请求将返回 403。
列出用量记录
返回一页你的团队的用量记录,默认按最新优先排序。如果不提供 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
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 和 refinetext-to-3d-preview:仅 preview 任务text-to-3d-refine:仅 refine 任务image-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- 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请求头中发送的标签。如果没有则为{}。参见元数据。