Usage API

Liệt kê các tác vụ API đã hoàn tất của nhóm bạn và số tín dụng mỗi tác vụ đã sử dụng, dùng cho xuất hóa đơ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 nó, 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.

GET/openapi/v1/usage/tasks

Liệt kê bản ghi sử dụng

Trả về một trang bản ghi sử dụng của nhóm bạn, theo mặc định là mới nhất trước. Nếu không có start_time và end_time, các bản ghi bao gồm 30 ngày gần nhất. Gọi endpoint này là miễn phí.

Các bản ghi bao gồm những tác vụ sau:

Tác vụ API đã hoàn tất với trạng thái SUCCEEDED hoặc FAILED
Tác vụ của mọi thành viên hiện tại của nhóm, từ bất kỳ khóa API nào của họ
Tác vụ bạn đã xóa, và tác vụ có tệp đã hết hạn

Các bản ghi không bao gồm những tác vụ sau:

Tác vụ vẫn đang ở trạng thái PENDING hoặc IN_PROGRESS, và tác vụ CANCELED
Tác vụ của những người đã rời nhóm
Tác vụ Creative Lab
Tác vụ do các AI agent của Meshy thực hiện
Công việc được thực hiện trong ứng dụng web Meshy

Một tác vụ chỉ xuất hiện trong bản ghi sau khi nó hoàn tất, trong khung thời gian của created_at. Meshy tính tín dụng khi nó tạo một tác vụ, vì vậy một tác vụ vẫn đang chạy sẽ không có trong bản ghi. Trước khi đối chiếu các bản ghi với số dư tín dụng của bạn, hãy lấy lại các khung thời gian gần đây, hoặc xuất sau một khoảng trễ ngắn.

Nếu nhóm của bạn có thời hạn lưu trữ dữ liệu, khung thời gian sẽ không bắt đầu sớm hơn thời hạn đó cho phép.

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": {}
  }
]

Tham số

Name
page_num
Type
integer
mặc định 1
Description
Trang cần trả về, từ 1 đến 255. Giá trị trên 255 sẽ trả về 400. Một khung thời gian chứa tối đa 255 trang, vì vậy hãy chia một bản xuất lớn thành các khung thời gian ngắn hơn.
Name
page_size
Type
integer
mặc định 10
Description
Số bản ghi mỗi trang, từ 1 đến 100. Giá trị từ 101 đến 255 trả về 100 bản ghi, và giá trị trên 255 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 đọc 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 của khung thời gian, dưới dạng dấu thời gian RFC 3339, ví dụ 2026-08-01T00:00:00Z. Bản ghi bao gồm các tác vụ được tạo vào hoặc sau thời điểm này. Bỏ qua tham số này để khung thời gian bắt đầu từ 30 ngày trước end_time.
Khung thời gian có thể kéo dài tối đa 366 ngày. Một khung thời gian dài hơn sẽ trả về 400, vì vậy hãy chia một bản xuất dài hơn thành nhiều khung thời gian.
Name
end_time
Type
string
Description
Thời điểm kết thúc của khung thời gian, dưới dạng dấu thời gian RFC 3339. Bản ghi 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 để khung thời gian kết thúc tại thời điểm bạn 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 cùng tên với 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à refine
- text-to-3d-preview: chỉ tác vụ preview
- text-to-3d-refine: chỉ tác vụ 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
Trạng thái cần bao gồm, SUCCEEDED hoặc FAILED. Bỏ qua tham số này để bao gồm cả hai. Bất kỳ giá trị nào khác sẽ trả về 400.

Trả về

Trả về một mảng các bản ghi sử dụng. Mảng này rỗng khi không có bản ghi nào khớp.

Chế độ lỗi

Name
400 - Bad Request
Description
Một tham số không hợp lệ, và thông báo lỗi cho biết 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 này không phải là thành viên đang hoạt động của nhóm Studio hoặc Enterprise. Thông báo 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 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 bản ghi 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ụ, cùng với ID mà endpoint tạo 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 bản ghi image-to-3d.
Name
endpoint
Type
string
Description
Endpoint mà tác vụ đã chạy trên đó, ví dụ image-to-3d hoặc rig. Một tác vụ Văn bản sang 3D hiển thị giai đoạn của nó, text-to-3d-preview hoặc text-to-3d-refine.
Các bản ghi cũ hơn có thể có tên của các endpoint đã ngừng hoạt động, mà bộ lọc endpoints không chấp nhận.
Name
status
Type
string
Description
Trạng thái cuối cùng của tác vụ, SUCCEEDED hoặc FAILED.
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 tất, tính bằng mili giây Unix. null nếu tác vụ không có thời điểm hoàn tất.
Name
consumed_credits
Type
integer
Description
Số tín dụng tác vụ đã sử dụng, sau khi hoàn tiền. 0 đối với tác vụ thất bại, vì Meshy sẽ hoàn lại tín dụng, và đối với 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ụ này. Đối với tác vụ chạy bằng cách đă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 bao giờ bị tính phí, chẳng hạn như 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 đó, để 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_name rỗng, và đối với các lượt đă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-Metadata khi tác vụ được tạo. {} nếu không có. Xem Metadata.