API Penggunaan

Senaraikan tugas API pasukan anda yang telah selesai dan kredit yang digunakan oleh setiap satu, untuk eksport pengebilan dan laporan kos.

Untuk memanggil endpoint ini, gunakan kunci API ahli aktif pasukan Studio atau Enterprise. Mana-mana ahli boleh memanggilnya, bukan hanya pemilik dan admin. Dengan sebarang kunci API lain, permintaan akan memulangkan 403.

GET/openapi/v1/usage/tasks

Senaraikan rekod penggunaan

Memulangkan satu halaman rekod penggunaan pasukan anda, secara lalai bermula dengan yang terbaru. Tanpa start_time dan end_time, rekod merangkumi 30 hari terakhir. Memanggil endpoint ini adalah percuma.

Rekod ini termasuk tugas berikut:

Tugas API yang selesai sebagai SUCCEEDED atau FAILED
Tugas setiap ahli pasukan semasa, daripada mana-mana kunci API mereka
Tugas yang anda padam, dan tugas yang fail-failnya telah tamat tempoh

Rekod ini tidak termasuk tugas berikut:

Tugas yang masih PENDING atau IN_PROGRESS, dan tugas CANCELED
Tugas orang yang telah meninggalkan pasukan
Tugas Creative Lab
Tugas yang dijalankan oleh ejen AI Meshy
Kerja yang dilakukan dalam aplikasi web Meshy

Sesuatu tugas muncul dalam rekod hanya selepas ia selesai, dalam tempoh created_at-nya. Meshy mengenakan caj kredit apabila ia mencipta tugas, jadi tugas yang masih berjalan tidak akan muncul dalam rekod. Sebelum anda menyesuaikan rekod dengan baki kredit anda, tarik semula tempoh terkini, atau eksport selepas penangguhan singkat.

Jika pasukan anda mempunyai tempoh penyimpanan data, tempoh itu tidak akan bermula lebih awal daripada yang dibenarkan oleh tempoh tersebut.

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": {}
  }
]

Parameter

Name
page_num
Type
integer
lalai 1
Description
Halaman untuk dipulangkan, dari 1 hingga 255. Nilai melebihi 255 memulangkan 400. Satu tempoh menampung paling banyak 255 halaman, jadi pecahkan eksport besar kepada tempoh yang lebih pendek.
Name
page_size
Type
integer
lalai 10
Description
Bilangan rekod setiap halaman, dari 1 hingga 100. Nilai dari 101 hingga 255 memulangkan 100 rekod, dan nilai melebihi 255 memulangkan 400.
Name
sort_by
Type
string
lalai -created_at
Description
Susunan isihan.
Nilai yang tersedia:
- +created_at: paling lama dahulu
- -created_at: paling baru dahulu
Dalam URL, tulis + sebagai %2B. Jika tidak, + akan dibaca sebagai ruang, dan permintaan akan memulangkan 400.
Name
start_time
Type
string
Description
Permulaan tempoh, sebagai cap masa RFC 3339, contohnya 2026-08-01T00:00:00Z. Rekod termasuk tugas yang dicipta pada atau selepas masa ini. Biarkan kosong untuk memulakan tempoh 30 hari sebelum end_time.
Tempoh boleh merangkumi paling banyak 366 hari. Tempoh yang lebih panjang memulangkan 400, jadi pecahkan eksport yang lebih panjang kepada beberapa tempoh.
Name
end_time
Type
string
Description
Penghujung tempoh, sebagai cap masa RFC 3339. Rekod termasuk tugas yang dicipta sebelum masa ini. Biarkan kosong untuk menamatkan tempoh pada masa permintaan anda.
Name
endpoints
Type
string
Description
Senarai endpoint yang dipisahkan koma untuk disertakan, menggunakan nama yang sama seperti medan endpoint. Biarkan kosong untuk menyertakan setiap endpoint. Nama yang tidak dikenali memulangkan 400.
Nilai yang tersedia:
- text-to-3d: setiap tugas Teks ke 3D, preview dan refine
- text-to-3d-preview: tugas preview sahaja
- text-to-3d-refine: tugas refine sahaja
- 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
Name
status
Type
string
Description
Status untuk disertakan, SUCCEEDED atau FAILED. Biarkan kosong untuk menyertakan kedua-duanya. Sebarang nilai lain memulangkan 400.

Pemulangan

Memulangkan array rekod penggunaan. Array ini kosong apabila tiada rekod yang sepadan.

Mod kegagalan

Name
400 - Bad Request
Description
Satu parameter tidak sah, dan mesej ralat menyatakan yang mana satu. Betulkan parameter itu, kemudian hantar permintaan semula.
Name
401 - Unauthorized
Description
Kunci API tiada atau tidak sah. Semak header Authorization.
Name
403 - Forbidden
Description
Akaun kunci API bukan ahli aktif pasukan Studio atau Enterprise. Mesejnya ialah This endpoint is available on Studio and Enterprise plans. Gunakan kunci API ahli pasukan Studio atau Enterprise.
Name
429 - Too Many Requests
Description
Anda menghantar terlalu banyak permintaan. Tunggu selama bilangan saat yang dinyatakan dalam Retry-After, kemudian cuba semula.

Objek rekod penggunaan

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 tugas, ID yang sama yang dipulangkan oleh endpoint yang mencipta tugas itu. Untuk mendapatkan tugas itu sendiri, dengan URL outputnya, hantar ID tersebut ke laluan get endpoint itu, contohnya GET /openapi/v1/image-to-3d/{task_id} untuk rekod image-to-3d.
Name
endpoint
Type
string
Description
Endpoint tempat tugas itu dijalankan, contohnya image-to-3d atau rig. Tugas Teks ke 3D menunjukkan peringkatnya, text-to-3d-preview atau text-to-3d-refine.
Rekod lama mungkin mempunyai nama endpoint yang telah dihentikan, yang tidak diterima oleh penapis endpoints.
Name
status
Type
string
Description
Status akhir tugas, SUCCEEDED atau FAILED.
Name
created_at
Type
timestamp
Description
Masa tugas dicipta, dalam milisaat Unix.
Name
finished_at
Type
timestamp
Description
Masa tugas selesai, dalam milisaat Unix. null jika tugas tidak mempunyai masa selesai.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas, selepas bayaran balik. 0 untuk tugas yang gagal, kerana Meshy membayar baliknya, dan untuk tugas percuma seperti Analisis kebolehcetakan.
Name
api_key_name
Type
string
Description
Nama kunci API yang menjalankan tugas. Untuk tugas yang dijalankan dengan log masuk aplikasi, ia adalah nama aplikasi tersebut, contohnya Meshy CLI.
Ia adalah rentetan kosong dalam sesetengah kes, contohnya:
- Tugas itu tidak pernah dikenakan caj, seperti tugas Analisis kebolehcetakan, yang percuma.
- Kunci API telah dipadam.
- Kunci API dicipta dalam beberapa minit yang lalu.
Name
api_key_suffix
Type
string
Description
Empat aksara terakhir kunci API itu, untuk membezakan kunci yang mempunyai nama sama. Rentetan kosong apabila api_key_name kosong, dan untuk log masuk aplikasi seperti Meshy CLI.
Name
metadata
Type
object
Description
Tag yang dihantar dalam header X-Meshy-Metadata semasa tugas dicipta. {} jika tiada. Lihat Metadata.