lowpoly sẽ ngừng hoạt động vào 30 thg 10, 2026. meshy-7 với vai trò mô hình tạo 3D sẽ ngừng hoạt động vào 31 thg 12, 2026; với vai trò mô hình texture thì vẫn dùng được. Hãy chuyển sang mô hình khác trước các ngày này để tránh lỗi yêu cầu. Xem tất cả mục ngừng hỗ trợ

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.


GET/openapi/v1/usage/tasks

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 SUCCEEDED hoặc FAILED
  • 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 PENDING hoặc IN_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

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ị lớn hơn 255 sẽ 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 đến 100. Giá trị từ 101 đến 255 sẽ trả về 100 hồ sơ, và giá trị lớn hơn 255 sẽ 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ước end_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à refine
    • text-to-3d-preview: chỉ các tác vụ preview
    • text-to-3d-refine: chỉ các 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
    • relief
  • 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. 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-3d hoặc rig. Một tác vụ Văn bản sang 3D sẽ hiển thị giai đoạn của nó, text-to-3d-preview hoặc text-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 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 thành, tính bằng mili giây Unix. null nế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_name rỗ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-Metadata khi tác vụ được tạo. {} nếu không có. Xem Metadata.