Usage API
Daftar tugas API tim Anda yang telah selesai beserta kredit yang digunakan masing-masing, untuk ekspor penagihan dan laporan biaya.
Untuk memanggil endpoint ini, gunakan kunci API dari anggota aktif tim Studio atau Enterprise. Setiap anggota dapat memanggilnya, bukan hanya pemilik dan admin. Dengan kunci API lainnya, permintaan akan mengembalikan 403.
Daftar catatan penggunaan
Mengembalikan satu halaman catatan penggunaan tim Anda, secara default diurutkan dari yang terbaru. Tanpa start_time dan end_time, catatan mencakup 30 hari terakhir. Memanggil endpoint ini tidak dikenakan biaya.
Catatan ini mencakup tugas-tugas berikut:
- Tugas API yang selesai dengan status
SUCCEEDEDatauFAILED - Tugas dari setiap anggota tim yang masih aktif saat ini, dari kunci API mana pun milik mereka
- Tugas yang Anda hapus, dan tugas yang berkasnya telah kedaluwarsa
Catatan ini tidak mencakup tugas-tugas berikut:
- Tugas yang masih berstatus
PENDINGatauIN_PROGRESS, serta tugas berstatusCANCELED - Tugas dari orang yang telah keluar dari tim
- Tugas Creative Lab
- Tugas yang dijalankan oleh agen AI Meshy
- Pekerjaan yang dilakukan di aplikasi web Meshy
Sebuah tugas hanya muncul dalam catatan setelah tugas tersebut selesai, dalam rentang created_at-nya. Meshy mengenakan kredit saat membuat tugas, sehingga tugas yang masih berjalan tidak akan muncul dalam catatan. Sebelum Anda mencocokkan catatan dengan saldo kredit Anda, ambil ulang rentang terbaru, atau lakukan ekspor setelah jeda singkat.
Jika tim Anda memiliki periode retensi data, rentang waktu tidak akan dimulai lebih awal dari yang diizinkan oleh periode tersebut.
Request
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
- default 1
- Description
Halaman yang akan dikembalikan, dari
1hingga255. Nilai di atas255akan mengembalikan400. Satu rentang waktu dapat menampung maksimal 255 halaman, jadi bagi ekspor besar menjadi beberapa rentang waktu yang lebih pendek.
- Name
- page_size
- Type
- integer
- default 10
- Description
Jumlah catatan per halaman, dari
1hingga100. Nilai dari101hingga255akan mengembalikan 100 catatan, dan nilai di atas255akan mengembalikan400.
- Name
- sort_by
- Type
- string
- default -created_at
- Description
Urutan pengurutan.
Nilai yang tersedia:
+created_at: terlama lebih dahulu-created_at: terbaru lebih dahulu
Dalam URL, tulis
+sebagai%2B. Jika tidak,+akan dibaca sebagai spasi, dan permintaan akan mengembalikan400.
- Name
- start_time
- Type
- string
- Description
Awal rentang waktu, sebagai stempel waktu RFC 3339, misalnya
2026-08-01T00:00:00Z. Catatan mencakup tugas yang dibuat pada atau setelah waktu ini. Kosongkan untuk memulai rentang waktu 30 hari sebelumend_time.Rentang waktu dapat mencakup maksimal 366 hari. Rentang waktu yang lebih panjang akan mengembalikan
400, jadi bagi ekspor yang lebih panjang menjadi beberapa rentang waktu.
- Name
- end_time
- Type
- string
- Description
Akhir rentang waktu, sebagai stempel waktu RFC 3339. Catatan mencakup tugas yang dibuat sebelum waktu ini. Kosongkan untuk mengakhiri rentang waktu pada saat permintaan Anda dibuat.
- Name
- endpoints
- Type
- string
- Description
Daftar endpoint yang akan disertakan, dipisahkan koma, menggunakan nama yang sama seperti pada bidang
endpoint. Kosongkan untuk menyertakan semua endpoint. Nama yang tidak dikenal akan mengembalikan400.Nilai yang tersedia:
text-to-3d: semua tugas Teks ke 3D, preview dan refinetext-to-3d-preview: hanya tugas previewtext-to-3d-refine: hanya tugas refineimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
Status yang akan disertakan,
SUCCEEDEDatauFAILED. Kosongkan untuk menyertakan keduanya. Nilai lain akan mengembalikan400.
Hasil yang dikembalikan
Mengembalikan array catatan penggunaan. Array akan kosong jika tidak ada catatan yang cocok.
Mode kegagalan
- Name
400 - Bad Request- Description
Sebuah parameter tidak valid, dan pesan error menunjukkan parameter yang mana. Perbaiki parameter tersebut, lalu kirim permintaan kembali.
- Name
401 - Unauthorized- Description
Kunci API tidak ada atau tidak valid. Periksa header
Authorization.
- Name
403 - Forbidden- Description
Akun kunci API bukan anggota aktif dari tim Studio atau Enterprise. Pesannya adalah
This endpoint is available on Studio and Enterprise plans. Gunakan kunci API dari anggota tim Studio atau Enterprise.
- Name
429 - Too Many Requests- Description
Anda mengirim terlalu banyak permintaan. Tunggu sejumlah detik sesuai nilai
Retry-After, lalu coba lagi.
Objek catatan 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 dengan yang dikembalikan oleh endpoint pembuatnya. Untuk mendapatkan tugas itu sendiri, beserta URL outputnya, kirim ID tersebut ke rute get milik endpoint itu, misalnya
GET /openapi/v1/image-to-3d/{task_id}untuk catatanimage-to-3d.
- Name
- endpoint
- Type
- string
- Description
Endpoint tempat tugas dijalankan, misalnya
image-to-3dataurig. Tugas Teks ke 3D menampilkan tahapannya,text-to-3d-previewatautext-to-3d-refine.Catatan yang lebih lama dapat memiliki nama endpoint yang sudah tidak digunakan lagi, yang tidak diterima oleh filter
endpoints.
- Name
- status
- Type
- string
- Description
Status akhir tugas,
SUCCEEDEDatauFAILED.
- Name
- created_at
- Type
- timestamp
- Description
Waktu tugas dibuat, dalam milidetik Unix.
- Name
- finished_at
- Type
- timestamp
- Description
Waktu tugas selesai, dalam milidetik Unix.
nulljika tugas tidak memiliki waktu selesai.
- Name
- consumed_credits
- Type
- integer
- Description
Jumlah kredit yang digunakan tugas, setelah pengembalian dana.
0untuk tugas yang gagal, karena Meshy mengembalikan kreditnya, dan untuk tugas gratis seperti Analisis kemampuan cetak.
- Name
- api_key_name
- Type
- string
- Description
Nama kunci API yang menjalankan tugas. Untuk tugas yang dijalankan dengan login aplikasi, ini adalah nama aplikasi tersebut, misalnya
Meshy CLI.Ini berupa string kosong dalam beberapa kasus, misalnya:
- Tugas tersebut tidak pernah dikenakan biaya, seperti tugas Analisis kemampuan cetak, yang gratis.
- Kunci API telah dihapus.
- Kunci API dibuat dalam beberapa menit terakhir.
- Name
- api_key_suffix
- Type
- string
- Description
Empat karakter terakhir dari kunci API tersebut, untuk membedakan kunci dengan nama yang sama. Berupa string kosong setiap kali
api_key_namekosong, dan untuk login aplikasi seperti Meshy CLI.
- Name
- metadata
- Type
- object
- Description
Tag yang dikirim dalam header
X-Meshy-Metadatasaat tugas dibuat.{}jika tidak ada. Lihat Metadata.