API Penggunaan

API Penggunaan memaparkan sejarah tugas API pasukan anda beserta kredit yang digunakan oleh setiap satu. Tapis mengikut tempoh masa, endpoint, atau status, dan lungsuri hasil secara berhalaman untuk dieksport 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

Senaraikan Rekod Penggunaan

Memaparkan satu halaman tugas API pasukan, bermula dari yang terbaharu. Tanpa tempoh 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.
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 (cth. 2026-08-01T00:00:00Z). Lalai kepada 30 hari sebelum end_time. Tempoh boleh meliputi paling lama 1 tahun — untuk eksport 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 — dengan text-to-3d sebagai kategori 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.

Pulangan

Memulangkan senarai berhalaman 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 hasil tempoh tersebut — tarik semula tempoh terkini (atau eksport dengan sedikit kelewatan) jika jumlah anda perlu sepadan tepat dengan baki kredit anda.

Pasukan dengan polisi pengekalan data tersuai akan menerima rekod dalam tempoh pengekalan yang 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"
  }
]

Objek Rekod Penggunaan

Name
task_id
Type
string
Description
ID tugas yang dibilkan oleh rekod ini — ID yang sama seperti yang dipulangkan oleh endpoint pencipta. Untuk mendapatkan tugas itu sendiri (termasuk model output atau URL imej, yang ditandatangani semula pada setiap bacaan), hantarkannya kepada endpoint dapatan semula yang berkaitan, cth. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
Endpoint tempat tugas dijalankan, cth. 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 penyempurnaan, dalam milisaat. null jika tugas tidak membawa masa penyempurnaan.
Name
consumed_credits
Type
integer
Description
Kredit yang digunakan oleh tugas ini. Memulangkan 0 untuk tugas FAILED (kredit dikembalikan apabila gagal).
Name
api_key_name
Type
string
Description
Nama paparan kunci API yang menjalankan tugas. Kekal terisi untuk kunci yang telah dibatalkan, supaya perbelanjaan sejarah kekal boleh dikaitkan selepas penggantian 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"
}