Usage API

Usage API memaparkan tugasan API bersejarah pasukan anda beserta kredit yang digunakan oleh setiap satu. Tapis mengikut tempoh masa, endpoint, atau status, dan lungsuri hasilnya untuk diexport secara pukal.

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

GET/openapi/v1/usage/tasks

List Usage Records

Memaparkan satu halaman tugasan API pasukan, yang terbaharu dahulu. Tanpa julat masa yang 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 diisih.
Nilai yang tersedia:
- +created_at: Isih mengikut masa pembuatan secara menaik.
- -created_at: Isih mengikut masa pembuatan 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 ini boleh merangkumi paling lama 1 tahun — untuk export yang lebih besar, lungsuri tempoh 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 dipisahkan 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 — di mana text-to-3d merupakan payung yang meliputi kedua-dua fasa preview dan refine. Ketepikan untuk menyertakan semua endpoint.
Name
status
Type
string
Description
Tapis mengikut status terminal tugasan: SUCCEEDED atau FAILED. Ketepikan untuk menyertakan kedua-duanya.

Pemulangan

Memaparkan senarai bersempadan halaman bagi The Usage Record Objects.

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

Pasukan dengan dasar tempoh penyimpanan data tersuai akan menerima rekod dalam tempoh penyimpanan yang telah dikonfigurasikan.

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 tugasan yang direkodkan oleh rekod ini — ID yang sama seperti yang dikembalikan oleh endpoint pembuatannya. Untuk mendapatkan tugasan itu sendiri (termasuk URL model output atau imej, yang ditandatangani semula pada setiap bacaan), hantarkannya ke endpoint pengambilan yang berkaitan, contohnya GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
Endpoint tempat tugasan itu dijalankan, contohnya image-to-3d atau text-to-3d-refine. Tugasan Teks ke 3D melaporkan fasanya (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Status terminal tugasan: SUCCEEDED atau FAILED.
Name
created_at
Type
timestamp
Description
Cap masa pembuatan tugasan, dalam milisaat.
Name
finished_at
Type
timestamp
Description
Cap masa penyiapan, dalam milisaat. null jika tugasan tidak mempunyai masa penyiapan.
Name
consumed_credits
Type
integer
Description
Kredit yang digunakan oleh tugasan ini. Memulangkan 0 untuk tugasan FAILED (kredit dikembalikan semula apabila gagal).
Name
api_key_name
Type
string
Description
Nama paparan kunci API yang menjalankan tugasan itu. Kekal terisi untuk kunci yang dibatalkan, supaya perbelanjaan sejarah kekal dapat dikesan selepas penggantian kunci.
Name
api_key_suffix
Type
string
Description
Empat aksara terakhir kunci API tersebut, untuk membezakan kunci yang mempunyai nama 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"
}