Meshy API Webhooks vs Polling: Kapan Hasil Siap

Tugas generasi Meshy API (Text to 3D, Image to 3D, Rigging, dan lainnya) berjalan secara asinkron — Anda mengirimkan tugas lalu perlu mengetahui kapan tugas tersebut selesai sebelum mengambil hasilnya. Artikel ini menjelaskan siklus hidup tugas dan dua cara yang didukung untuk mengetahui kapan sebuah tugas telah selesai: polling dan webhook — serta cara menghindari masalah paling umum berupa "error saat mengambil model".

Setiap tugas generasi melewati sejumlah kecil status, yang dikembalikan di field status pada objek tugas:

• PENDING — tugas telah masuk antrean tetapi pemrosesan belum dimulai.

• IN_PROGRESS — tugas sedang aktif diproses. Field progress (0-100) meningkat seiring pekerjaan yang selesai.

• SUCCEEDED — tugas berhasil diselesaikan dan progress adalah 100. URL hasil (file model, tekstur, pratinjau) kini tersedia di respons.

• FAILED — tugas tidak dapat diselesaikan. Kredit untuk tugas yang gagal akan dikembalikan secara otomatis.

• CANCELED — tugas dibatalkan sebelum selesai.

Aturan terpenting saat integrasi dengan API: jangan pernah mencoba mengambil atau menggunakan URL hasil sebelum status tugas adalah SUCCEEDED. Membaca hasil saat tugas masih PENDING atau IN_PROGRESS adalah penyebab paling umum dari laporan "error saat mengambil model".

Polling berarti memanggil endpoint "get task" untuk ID tugas Anda berulang kali hingga mencapai status terminal (SUCCEEDED, FAILED, atau CANCELED). Loop polling sederhana terlihat seperti ini:

• Kirim permintaan generasi dan simpan id tugas yang dikembalikan.

• Panggil endpoint "retrieve task" yang sesuai (misalnya, endpoint task-by-id Text to 3D atau Image to 3D) secara berkala — beberapa detik biasanya cukup.

• Periksa field status pada setiap respons. Lanjutkan polling selama statusnya PENDING atau IN_PROGRESS.

• Hentikan polling segera setelah status adalah SUCCEEDED (baca URL hasil), FAILED, atau CANCELED.

• Tambahkan pembatas timeout/max-attempts yang wajar di klien Anda agar tugas yang macet tidak terus dipolling selamanya.

Polling sederhana dan bekerja dengan baik untuk skrip, pekerjaan batch, dan integrasi volume rendah. Untuk integrasi volume tinggi atau yang sensitif terhadap latensi, webhook biasanya lebih cocok.

Alih-alih berulang kali bertanya "apakah sudah selesai?", Anda dapat meminta Meshy untuk memberi tahu server Anda begitu sebuah tugas selesai. Untuk menggunakan webhook:

• Konfigurasikan URL webhook (callback) yang dapat dijangkau Meshy — ini biasanya diatur pada level pengaturan akun/API atau dikirim sebagai parameter pada permintaan generasi, tergantung pada endpoint.

• Pastikan endpoint Anda dapat diakses secara publik melalui HTTPS dan merespons dengan cepat (kembalikan status 2xx segera, lalu proses payload secara asinkron).

• Ketika tugas mencapai status terminal, Meshy mengirimkan payload ke endpoint Anda yang berisi id tugas dan status akhirnya.

• Setelah menerima, cari detail tugas lengkap berdasarkan id melalui API alih-alih hanya mempercayai isi webhook, untuk memastikan Anda memiliki hasil yang otoritatif dan terbaru.

Webhook mengurangi panggilan API yang tidak perlu dan memberi Anda notifikasi hampir seketika, tetapi Anda tetap harus mempertahankan fallback polling berkala untuk tugas-tugas yang pengiriman webhooknya mungkin terlewat atau tertunda (misalnya karena masalah jaringan sementara di sisi Anda).

Baik Anda menggunakan polling maupun webhook, kode penanganan hasil Anda harus bersifat idempoten — aman untuk dijalankan lebih dari sekali untuk tugas yang sama tanpa efek samping. Ini penting karena:

• Webhook mungkin dikirim lebih dari sekali untuk tugas yang sama (retry di sisi pengirim, duplikasi jaringan, dll.).

• Loop polling dan handler webhook mungkin sama-sama mencoba memproses tugas yang sama yang telah selesai jika keduanya berjalan.

Untuk tetap idempoten, dasarkan logika pemrosesan Anda pada id tugas — misalnya, periksa apakah Anda sudah menyimpan/mengunduh hasil untuk id tersebut sebelum melakukannya lagi, dan jadikan "tandai sebagai diproses" sebagai satu langkah atomik di database Anda sendiri.

Respons dengan "status": "SUCCEEDED" dan "progress": 100 adalah satu-satunya sinyal yang menjamin payload hasil (URL model, tekstur, thumbnail) sudah lengkap dan aman digunakan. Secara konkret, dalam kode Anda:

• Verifikasi status === "SUCCEEDED" sebelum membaca apa pun dari field URL result/model.

• Jangan hanya mengandalkan progress — selalu periksa status juga, karena progress dapat sesaat menunjukkan nilai tinggi sebelum tugas sepenuhnya diselesaikan.

• Unduh file hasil segera setelah SUCCEEDED — aset yang dihasilkan hanya disimpan di server Meshy untuk waktu terbatas, setelah itu URL tidak akan dapat diakses lagi.

Sebagian besar laporan "saya tidak bisa mengambil model saya" dapat ditelusuri ke salah satu penyebab berikut:

• Mengambil terlalu dini. Memanggil URL hasil, atau membaca field model, sebelum status adalah SUCCEEDED. Ini jauh merupakan penyebab paling sering.

• Aset kedaluwarsa. Menunggu terlalu lama setelah SUCCEEDED untuk mengunduh — URL hasil berhenti berfungsi setelah periode retensi untuk jenis tugas tersebut berlalu.

• Menggunakan ID tugas yang usang atau salah — misalnya, menggunakan kembali ID dari permintaan sebelumnya yang tidak terkait.

• Menganggap FAILED sebagai status sementara dan terus mempolling tugas yang sudah gagal alih-alih mengirim ulang.

• Masalah jaringan/timeout antara server Anda dan Meshy yang salah ditafsirkan sebagai masalah generasi.

Jika hasil generasi tidak sesuai harapan Anda, atau permintaan gagal total, perhatikan hal-hal berikut:

• Meshy API saat ini tidak mendukung retry tugas yang ada secara langsung — untuk mencoba lagi, kirimkan permintaan generasi baru, yang akan mengonsumsi kredit seperti biasa.

• Untuk kegagalan jaringan sementara saat memanggil API (timeout, respons 5xx), exponential backoff singkat sebelum mengirim ulang permintaan adalah hal yang wajar.

• Untuk polling itu sendiri, ulangi panggilan "get task" pada error jaringan sementara, tetapi jangan menganggap satu kegagalan polling sebagai kegagalan generasi — hanya percayai field status setelah Anda mendapatkan respons yang berhasil.

• Jika Anda memerlukan fungsi retry bawaan untuk generasi, hubungi tim sales Meshy mengenai opsi paket enterprise.

Ini hampir selalu terjadi karena kode mencoba membaca hasil sebelum tugas selesai. Selalu pastikan status adalah SUCCEEDED (dan progress adalah 100) sebelum mengambil URL model.

Polling lebih sederhana untuk disiapkan dan cukup baik untuk skrip volume rendah atau sekali pakai. Webhook lebih baik untuk integrasi produksi dengan banyak tugas bersamaan, karena menghindari permintaan berulang yang tidak perlu dan memberi tahu Anda segera saat tugas selesai.

Tangani secara idempoten — periksa id tugas terhadap yang sudah Anda proses, dan lewati pemrosesan ulang jika sudah pernah ditangani.

Beralihlah ke polling tugas berdasarkan id secara langsung. Juga pastikan endpoint Anda dapat diakses secara publik melalui HTTPS dan mengembalikan respons 2xx dengan cepat, karena endpoint yang lambat atau tidak dapat dijangkau dapat menyebabkan masalah pengiriman.

Saat ini belum bisa — Anda perlu mengirimkan permintaan generasi baru, yang mengonsumsi kredit seperti biasa. Hubungi sales mengenai opsi enterprise jika Anda memerlukan dukungan retry bawaan.

File hasil hanya disimpan di server Meshy untuk waktu terbatas setelah tugas selesai, jadi unduh output ke penyimpanan Anda sendiri segera setelah tugas berhasil alih-alih menunggu.

• Mengapa Saya Selalu Mengalami Error Saat Mengambil Model dari Hasil Generasi Menggunakan API?