Usage API

Usage API trả về danh sách các tác vụ API trong lịch sử 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ề 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ã lỗi 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 tiên. Nếu không có 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 dùng cho phân trang.

  • Name
    page_size
    Type
    integer
    mặc định 10
    Description

    Giới hạn số lượng mục trên mỗi 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 dữ liệu 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ù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, print-split — 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 tác vụ: SUCCEEDED hoặc FAILED. Bỏ trống để bao gồm cả hai.

Trả về

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

Các bản ghi chỉ bao gồm các tác vụ đã đạt trạng thái cuối cùng. Tín dụng được tính khi tác vụ được tạo, do đó 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 xuất hiện trong kết quả của khoảng thời gian đó — 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 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 tác vụ đã 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 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à 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 có 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 tác vụ 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 đầy đủ ngay cả với các khóa đã bị thu hồi, để chi tiêu trong lịch sử vẫn có thể được quy về đúng khóa 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"
}