Usage API

Usage API trả về lịch sử các API task của team bạn cùng với số tín dụng mà mỗi task đã tiêu tốn. Lọc theo khoảng thời gian, endpoint, hoặc trạng thái, và duyệt qua các trang kết quả để xuất hàng loạt.

Khả năng sử dụng. Khóa API phải thuộc về một team Studio hoặc Enterprise; các khóa thuộc gói khác, hoặc không thuộc team nào, sẽ nhận mã 403.

GET/openapi/v1/usage/tasks

List Usage Records

Trả về một trang các API task của team, mới nhất trước. Nếu không chỉ định khoảng thời gian cụ thể, phản hồi sẽ bao gồm 30 ngày gần nhất.

Tham số

Name
page_num
Type
integer
mặc định 1
Description
Số trang cho phân trang.
Name
page_size
Type
integer
mặc định 10
Description
Giới hạn kích thước trang. Tối đa cho phép là 100 mục.
Name
sort_by
Type
string
mặc định -created_at
Description
Trường dùng để sắp xếp.
Các giá trị khả dụng:
- +created_at: Sắp xếp theo thời gian tạo tăng dần.
- -created_at: Sắp xếp theo thời gian tạo giảm dần.
Name
start_time
Type
string
Description
Thời điểm bắt đầu của khoảng created_at, dưới dạng dấu thời gian RFC 3339 (ví dụ: 2026-08-01T00:00:00Z). Mặc định là 30 ngày trước end_time. Khoảng thời gian tối đa là 1 năm — với các lần xuất lớn hơn, hãy duyệt qua từng khoảng liên tiếp.
Name
end_time
Type
string
Description
Thời điểm kết thúc của khoảng created_at, dưới dạng dấu thời gian RFC 3339. Mặc định là thời điểm hiện tại.
Name
endpoints
Type
string
Description
Danh sách tên endpoint cần bao gồm, phân tách bằng dấu phẩy. Chấp nhận cùng các giá trị mà trường phản hồi endpoint mang — 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 — trong đó text-to-3d là tên gọi chung bao trùm cả hai giai đoạn preview và refine. Bỏ trống để bao gồm tất cả endpoint.
Name
status
Type
string
Description
Lọc theo trạng thái cuối cùng của task: SUCCEEDED hoặc FAILED. Bỏ trống để bao gồm cả hai.

Kết quả trả về

Trả về danh sách phân trang các The Usage Record Objects.

Các bản ghi bao gồm các task đã đạt trạng thái cuối cùng. Tín dụng được trừ khi task được tạo, vì vậy một task vẫn đang chạy tại thời điểm bạn xuất dữ liệu sẽ chưa xuất hiện trong kết quả của khoảng đó — hãy tải lại các khoảng thời gian gần đây (hoặc xuất dữ liệu với một độ trễ ngắn) nếu bạn cần tổng số khớp chính xác với số dư tín dụng của mình.

Các team có chính sách lưu trữ dữ liệu tùy chỉnh sẽ nhận được các bản ghi trong phạm vi thời gian lưu trữ đã cấu hình.

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

The Usage Record Object

Name
task_id
Type
string
Description
ID của task mà bản ghi này tính phí — cùng ID mà endpoint tạo ra đã trả về. Để lấy chính task đó (bao gồm URL model hoặc hình ảnh đầu ra, được ký lại mỗi lần đọc), hãy truyền ID này vào endpoint truy xuất tương ứng, ví dụ: GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
Endpoint mà task đã chạy, ví dụ: image-to-3d hoặc text-to-3d-refine. Các task Văn bản sang 3D sẽ báo cáo giai đoạn của chúng (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Trạng thái cuối cùng của task: SUCCEEDED hoặc FAILED.
Name
created_at
Type
timestamp
Description
Dấu thời gian tạo task, tính bằng mili-giây.
Name
finished_at
Type
timestamp
Description
Dấu thời gian hoàn thành, tính bằng mili-giây. Trả về null nếu task không có thời gian hoàn thành.
Name
consumed_credits
Type
integer
Description
Số tín dụng đã tiêu tốn cho task này. Trả về 0 đối với các task FAILED (tín dụng được hoàn lại khi thất bại).
Name
api_key_name
Type
string
Description
Tên hiển thị của khóa API đã chạy task. Vẫn được điền đầy đủ ngay cả với các khóa đã bị thu hồi, để chi tiêu lịch sử vẫn có thể truy vết được sau khi khóa được luân chuyển.
Name
api_key_suffix
Type
string
Description
Bốn ký tự cuối của khóa API đó, dùng để phân biệt các khóa có cùng tên.

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"
}