lowpoly akan dihentikan pada 30 Okt 2026. meshy-7 sebagai model penjanaan 3D akan dihentikan pada 31 Dis 2026; sebagai model tekstur ia kekal tersedia. Tukar model sebelum tarikh-tarikh ini untuk mengelakkan ralat permintaan. Lihat semua penamatan

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 bagi ahli aktif pasukan Studio atau Enterprise. Mana-mana ahli boleh memanggilnya, bukan hanya pemilik dan pentadbir. Dengan kunci API lain, permintaan akan mengembalikan 403.


GET/openapi/v1/usage/tasks

Senaraikan rekod penggunaan

Mengembalikan satu halaman rekod penggunaan pasukan anda, secara lalai yang terbaharu dahulu. Tanpa start_time dan end_time, rekod merangkumi 30 hari terakhir. Memanggil endpoint ini adalah percuma.

Rekod merangkumi tugas-tugas berikut:

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

Rekod tidak merangkumi tugas-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 hanya muncul dalam rekod selepas ia selesai, dalam tempoh created_at-nya. Meshy mengenakan caj kredit apabila ia mencipta tugas, jadi tugas yang masih berjalan akan tiada dalam rekod. Sebelum anda menyesuaikan rekod dengan baki kredit anda, tarik semula tempoh terkini, atau eksport selepas sedikit kelewatan.

Jika pasukan anda mempunyai tempoh pengekalan data, tempoh bermula tidak 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 yang hendak dikembalikan, dari 1 hingga 255. Nilai melebihi 255 mengembalikan 400. Satu tempoh memegang paling banyak 255 halaman, jadi pecahkan eksport yang 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 mengembalikan 100 rekod, dan nilai melebihi 255 mengembalikan 400.

  • Name
    sort_by
    Type
    string
    lalai -created_at
    Description

    Susunan isihan.

    Nilai yang tersedia:

    • +created_at: paling lama dahulu
    • -created_at: paling baharu dahulu

    Dalam URL, tulis + sebagai %2B. Jika tidak, + akan dibaca sebagai ruang, dan permintaan akan mengembalikan 400.

  • Name
    start_time
    Type
    string
    Description

    Permulaan tempoh, sebagai cap masa RFC 3339, contohnya 2026-08-01T00:00:00Z. Rekod merangkumi tugas yang dicipta pada atau selepas masa ini. Tinggalkan kosong untuk memulakan tempoh 30 hari sebelum end_time.

    Tempoh boleh merangkumi paling banyak 366 hari. Tempoh yang lebih panjang mengembalikan 400, jadi pecahkan eksport yang lebih panjang kepada beberapa tempoh.

  • Name
    end_time
    Type
    string
    Description

    Penghujung tempoh, sebagai cap masa RFC 3339. Rekod merangkumi tugas yang dicipta sebelum masa ini. Tinggalkan kosong untuk menamatkan tempoh pada masa permintaan anda.

  • Name
    endpoints
    Type
    string
    Description

    Senarai endpoint yang hendak disertakan, dipisahkan koma, menggunakan nama yang sama seperti medan endpoint. Tinggalkan kosong untuk menyertakan setiap endpoint. Nama yang tidak dikenali mengembalikan 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
    • relief
  • Name
    status
    Type
    string
    Description

    Status yang hendak disertakan, SUCCEEDED atau FAILED. Tinggalkan kosong untuk menyertakan kedua-duanya. Sebarang nilai lain mengembalikan 400.

Pulangan

Mengembalikan susunan rekod penggunaan. Susunan adalah 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 tersebut, kemudian hantar permintaan semula.

  • Name
    401 - Unauthorized
    Description

    Kunci API hilang 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 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 dikembalikan oleh endpoint yang menciptanya. Untuk mendapatkan tugas itu sendiri, berserta 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 tersebut 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 tersebut. 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 tersebut tidak pernah dikenakan caj, seperti tugas Analisis kebolehcetakan, yang percuma.
    • Kunci API tersebut telah dipadam.
    • Kunci API tersebut dicipta dalam beberapa minit yang lepas.
  • Name
    api_key_suffix
    Type
    string
    Description

    Empat aksara terakhir kunci API tersebut, untuk membezakan kunci dengan nama yang 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.