Usage API
Liệt kê các tác vụ API đã hoàn thành của nhóm bạn cùng với số tín dụng mà mỗi tác vụ đã sử dụng, phục vụ cho việc xuất dữ liệu thanh toán và báo cáo chi phí.
Để gọi endpoint này, hãy dùng khóa API của một thành viên đang hoạt động trong nhóm Studio hoặc Enterprise. Bất kỳ thành viên nào cũng có thể gọi, không chỉ chủ sở hữu và quản trị viên. Với bất kỳ khóa API nào khác, yêu cầu sẽ trả về 403.
Liệt kê hồ sơ sử dụng
Trả về một trang hồ sơ sử dụng của nhóm bạn, mặc định mới nhất trước. Nếu không có start_time và end_time, các hồ sơ sẽ bao gồm 30 ngày gần nhất. Việc gọi endpoint này là miễn phí.
Các hồ sơ bao gồm những tác vụ sau:
- Các tác vụ API đã hoàn thành với trạng thái
SUCCEEDEDhoặcFAILED - Tác vụ của mọi thành viên hiện tại trong nhóm, từ bất kỳ khóa API nào của họ
- Các tác vụ bạn đã xóa, và các tác vụ có tệp đã hết hạn
Các hồ sơ không bao gồm những tác vụ sau:
- Các tác vụ vẫn đang ở trạng thái
PENDINGhoặcIN_PROGRESS, và các tác vụCANCELED - Tác vụ của những người đã rời khỏi nhóm
- Các tác vụ Creative Lab
- Các tác vụ do AI agent của Meshy thực hiện
- Công việc thực hiện trong ứng dụng web Meshy
Một tác vụ chỉ xuất hiện trong hồ sơ sau khi nó hoàn thành, trong khoảng thời gian của created_at. Meshy tính tín dụng ngay khi tạo tác vụ, vì vậy một tác vụ vẫn đang chạy sẽ không xuất hiện trong hồ sơ. Trước khi đối chiếu hồ sơ với số dư tín dụng của bạn, hãy lấy lại các khoảng thời gian gần đây, hoặc xuất dữ liệu sau một khoảng trễ ngắn.
Nếu nhóm của bạn có thời gian lưu trữ dữ liệu, khoảng thời gian sẽ không bắt đầu sớm hơn thời gian mà chính sách đó cho phép.
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": {}
}
]
Tham số
- Name
- page_num
- Type
- integer
- mặc định 1
- Description
Trang cần trả về, từ
1đến255. Giá trị lớn hơn255sẽ trả về400. Một khoảng thời gian chứa tối đa 255 trang, vì vậy hãy chia một lần xuất dữ liệu lớn thành các khoảng thời gian ngắn hơn.
- Name
- page_size
- Type
- integer
- mặc định 10
- Description
Số hồ sơ trên mỗi trang, từ
1đến100. Giá trị từ101đến255sẽ trả về 100 hồ sơ, và giá trị lớn hơn255sẽ trả về400.
- Name
- sort_by
- Type
- string
- mặc định -created_at
- Description
Thứ tự sắp xếp.
Các giá trị khả dụng:
+created_at: cũ nhất trước-created_at: mới nhất trước
Trong URL, hãy viết
+thành%2B. Nếu không,+sẽ được hiểu là dấu cách, và yêu cầu sẽ trả về400.
- Name
- start_time
- Type
- string
- Description
Thời điểm bắt đầu khoảng thời gian, dưới dạng dấu thời gian RFC 3339, ví dụ
2026-08-01T00:00:00Z. Hồ sơ sẽ bao gồm các tác vụ được tạo tại hoặc sau thời điểm này. Bỏ qua tham số này để bắt đầu khoảng thời gian 30 ngày trướcend_time.Khoảng thời gian có thể kéo dài tối đa 366 ngày. Khoảng thời gian dài hơn sẽ trả về
400, vì vậy hãy chia một lần xuất dữ liệu dài hơn thành nhiều khoảng thời gian.
- Name
- end_time
- Type
- string
- Description
Thời điểm kết thúc khoảng thời gian, dưới dạng dấu thời gian RFC 3339. Hồ sơ bao gồm các tác vụ được tạo trước thời điểm này. Bỏ qua tham số này để kết thúc khoảng thời gian tại thời điểm gửi yêu cầu.
- Name
- endpoints
- Type
- string
- Description
Danh sách các endpoint cần bao gồm, phân tách bằng dấu phẩy, theo đúng tên trong trường
endpoint. Bỏ qua tham số này để bao gồm mọi endpoint. Một tên không xác định sẽ trả về400.Các giá trị khả dụng:
text-to-3d: mọi tác vụ Văn bản sang 3D, cả preview và refinetext-to-3d-preview: chỉ các tác vụ previewtext-to-3d-refine: chỉ các tác vụ refineimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
Trạng thái cần bao gồm,
SUCCEEDEDhoặcFAILED. Bỏ qua tham số này để bao gồm cả hai. Mọi giá trị khác sẽ trả về400.
Giá trị trả về
Trả về một mảng các hồ sơ sử dụng. Mảng này sẽ rỗng khi không có hồ sơ nào khớp.
Các trường hợp lỗi
- Name
400 - Bad Request- Description
Một tham số không hợp lệ, và thông báo lỗi sẽ cho biết đó là tham số nào. Hãy sửa tham số đó rồi gửi lại yêu cầu.
- Name
401 - Unauthorized- Description
Khóa API bị thiếu hoặc không hợp lệ. Hãy kiểm tra tiêu đề
Authorization.
- Name
403 - Forbidden- Description
Tài khoản của khóa API không phải là thành viên đang hoạt động trong nhóm Studio hoặc Enterprise. Thông báo sẽ là
This endpoint is available on Studio and Enterprise plans. Hãy dùng khóa API của một thành viên trong nhóm Studio hoặc Enterprise.
- Name
429 - Too Many Requests- Description
Bạn đã gửi quá nhiều yêu cầu. Hãy đợi số giây được ghi trong
Retry-After, rồi thử lại.
Đối tượng hồ sơ sử dụng
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 tác vụ, giống với ID mà endpoint tạo ra tác vụ đã trả về. Để lấy chính tác vụ đó, cùng với các URL đầu ra của nó, hãy gửi ID này đến route lấy thông tin của endpoint đó, ví dụ
GET /openapi/v1/image-to-3d/{task_id}cho một hồ sơimage-to-3d.
- Name
- endpoint
- Type
- string
- Description
Endpoint mà tác vụ đã chạy trên đó, ví dụ
image-to-3dhoặcrig. Một tác vụ Văn bản sang 3D sẽ hiển thị giai đoạn của nó,text-to-3d-previewhoặctext-to-3d-refine.Các hồ sơ cũ hơn có thể mang tên của những endpoint đã ngừng hoạt động, mà bộ lọc
endpointskhông chấp nhận.
- Name
- status
- Type
- string
- Description
Trạng thái cuối cùng của tác vụ,
SUCCEEDEDhoặcFAILED.
- Name
- created_at
- Type
- timestamp
- Description
Thời điểm tác vụ được tạo, tính bằng mili giây Unix.
- Name
- finished_at
- Type
- timestamp
- Description
Thời điểm tác vụ hoàn thành, tính bằng mili giây Unix.
nullnếu tác vụ không có thời điểm hoàn thành.
- Name
- consumed_credits
- Type
- integer
- Description
Số tín dụng mà tác vụ đã sử dụng, sau khi hoàn trả.
0đối với một tác vụ thất bại, vì Meshy sẽ hoàn trả tín dụng, và đối với một tác vụ miễn phí như Phân tích khả năng in.
- Name
- api_key_name
- Type
- string
- Description
Tên của khóa API đã chạy tác vụ. Đối với tác vụ chạy bằng đăng nhập ứng dụng, đây là tên của ứng dụng, ví dụ
Meshy CLI.Trường này là một chuỗi rỗng trong một số trường hợp, ví dụ:
- Tác vụ chưa từng bị tính phí, chẳng hạn như một tác vụ Phân tích khả năng in, vốn miễn phí.
- Khóa API đã bị xóa.
- Khóa API được tạo trong vài phút gần đây.
- Name
- api_key_suffix
- Type
- string
- Description
Bốn ký tự cuối cùng của khóa API đó, dùng để phân biệt các khóa có cùng tên. Là một chuỗi rỗng bất cứ khi nào
api_key_namerỗng, và đối với các đăng nhập ứng dụng như Meshy CLI.
- Name
- metadata
- Type
- object
- Description
Các thẻ được gửi trong tiêu đề
X-Meshy-Metadatakhi tác vụ được tạo.{}nếu không có. Xem Metadata.