Usage API

Usage API trả về lịch sử các tác vụ API của nhóm bạn cùng với số tín dụng mà mỗi tác vụ đã tiêu thụ. Lọc theo khoảng thời gian, endpoint, hoặc trạng thái, và phân trang qua các 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 nhóm Studio hoặc Enterprise; các khóa thuộc gói khác, hoặc không thuộc nhóm nào, sẽ nhận mã 403.

GET/openapi/v1/usage/tasks

List Usage Records

Trả về một trang các tác vụ API của nhóm, 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ượt xuất lớn hơn, hãy phân trang qua các khoảng thời gian 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ác giá trị giống như trường phản hồi endpoint mang theo — 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à danh mục tổng quát bao gồm cả giai đoạn preview và refine. Bỏ trống để bao gồm tất cả các endpoint.

  • Name
    status
    Type
    string
    Description

    Lọc theo trạng thái cuối cùng của tác vụ: SUCCEEDED hoặc FAILED. Bỏ trống để bao gồm cả hai.

Trả về

Trả về một danh sách phân trang gồm các The Usage Record Objects.

Các bản ghi bao gồm các tác vụ đã đạt trạng thái cuối cùng. Tín dụng được tính phí khi một tác vụ được tạo, vì vậy một tác vụ vẫn đang chạy tại thời điểm bạn xuất dữ liệu sẽ chưa nằm trong kết quả của khoảng thời gian đó — hãy lấy 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 tổng số của bạn cần khớp chính xác với số dư tín dụng.

Các nhóm 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 khoảng 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 tác vụ mà bản ghi này tính phí — cùng ID mà endpoint tạo ra đã trả về. Để lấy chính tác vụ đó (bao gồm cả URL mô hình đầu ra hoặc hình ảnh, được ký lại mỗi lần đọc), hãy truyền nó vào endpoint truy xuất tương ứng, ví dụ GET /openapi/v1/{endpoint}/{task_id}.

  • Name
    endpoint
    Type
    string
    Description

    Endpoint mà tác vụ đã chạy, ví dụ image-to-3d hoặc text-to-3d-refine. Các tác vụ Văn bản sang 3D 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 tác vụ: SUCCEEDED hoặc FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

    Dấu thời gian tạo tác vụ, 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. null nếu tác vụ không mang thời gian hoàn thành.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số tín dụng đã tiêu thụ bởi tác vụ này. Trả về 0 đối với các tác vụ 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 tác vụ. Vẫn được điền cho cả các khóa đã bị thu hồi, để chi tiêu lịch sử vẫn có thể quy về đúng đối tượng sau khi xoay vòng khóa.

  • 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.

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