Usage API

Usage API mengembalikan rekod tugas API historik pasukan anda beserta kredit yang digunakan oleh setiap satu. Tapis mengikut julat masa, endpoint, atau status, dan lungsuri halaman keputusan untuk eksport secara pukal.

Ketersediaan. Kunci API mestilah dimiliki oleh pasukan Studio atau Enterprise; kunci pada pelan lain, atau tanpa pasukan, akan menerima 403.

GET/openapi/v1/usage/tasks

List Usage Records

Mengembalikan satu halaman tugas API pasukan, terbaharu dahulu. Tanpa julat masa yang dinyatakan secara jelas, respons meliputi 30 hari terakhir.

Parameter

Name
page_num
Type
integer
lalai 1
Description
Nombor halaman untuk penomboran halaman.
Name
page_size
Type
integer
lalai 10
Description
Had saiz halaman. Maksimum yang dibenarkan ialah 100 item.
Name
sort_by
Type
string
lalai -created_at
Description
Medan untuk disusun mengikut.
Nilai yang tersedia:
- +created_at: Susun mengikut masa penciptaan secara menaik.
- -created_at: Susun mengikut masa penciptaan secara menurun.
Name
start_time
Type
string
Description
Permulaan tempoh created_at, dalam bentuk cap masa RFC 3339 (contohnya 2026-08-01T00:00:00Z). Lalai kepada 30 hari sebelum end_time. Tempoh boleh merangkumi maksimum 1 tahun — untuk eksport yang lebih besar, lungsuri tempoh yang berturutan.
Name
end_time
Type
string
Description
Penghujung tempoh created_at, dalam bentuk cap masa RFC 3339. Lalai kepada masa semasa.
Name
endpoints
Type
string
Description
Senarai nama endpoint yang dipisahkan dengan koma untuk disertakan. Menerima nilai yang sama seperti yang dibawa oleh medan respons endpoint — 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 — di mana text-to-3d merupakan istilah payung yang meliputi kedua-dua fasa preview dan refine. Biarkan kosong untuk menyertakan semua endpoint.
Name
status
Type
string
Description
Tapis mengikut status akhir tugas: SUCCEEDED atau FAILED. Biarkan kosong untuk menyertakan kedua-duanya.

Mengembalikan

Mengembalikan senarai bernomborkan halaman bagi Objek Rekod Penggunaan.

Rekod meliputi tugas yang telah mencapai status akhir. Kredit dicaj apabila tugas dicipta, jadi tugas yang masih berjalan semasa anda mengeksport belum lagi berada dalam keputusan tempoh tersebut — tarik semula tempoh terkini (atau eksport dengan sedikit kelewatan) jika jumlah anda perlu sepadan tepat dengan baki kredit anda.

Pasukan dengan dasar pengekalan data tersuai menerima rekod dalam tempoh pengekalan yang telah dikonfigurasi.

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 tugas yang dicaj oleh rekod ini — ID yang sama seperti yang dikembalikan oleh endpoint yang mencipta tugas tersebut. Untuk mendapatkan tugas itu sendiri (termasuk model output atau URL imejnya, yang ditandatangani semula pada setiap bacaan), hantarkan ID tersebut kepada endpoint retrieve yang berkaitan, contohnya GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
Endpoint tempat tugas dijalankan, contohnya image-to-3d atau text-to-3d-refine. Tugas Teks ke 3D melaporkan fasanya (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Status akhir tugas: SUCCEEDED atau FAILED.
Name
created_at
Type
timestamp
Description
Cap masa penciptaan tugas, dalam milisaat.
Name
finished_at
Type
timestamp
Description
Cap masa penyelesaian, dalam milisaat. null jika tugas tidak membawa masa penyelesaian.
Name
consumed_credits
Type
integer
Description
Kredit yang digunakan oleh tugas ini. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan semula apabila gagal).
Name
api_key_name
Type
string
Description
Nama paparan kunci API yang menjalankan tugas tersebut. Kekal diisi untuk kunci yang dibatalkan, supaya perbelanjaan sejarah kekal boleh dikaitkan selepas penggiliran kunci.
Name
api_key_suffix
Type
string
Description
Empat aksara terakhir kunci API tersebut, untuk membezakan kunci yang mempunyai nama yang sama.

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