Webhook vs Polling Meshy API: Kapan Hasil Siap

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

Setiap tugas generasi melewati beberapa status, yang dikembalikan pada kolom status dari objek tugas:

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

• IN_PROGRESS — tugas sedang diproses. Kolom progress (0-100) meningkat seiring pekerjaan diselesaikan.

• SUCCEEDED — tugas selesai dengan sukses dan progress bernilai 100. URL hasil (file model, tekstur, pratinjau) kini tersedia dalam respons.

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

• CANCELED — tugas dibatalkan sebelum selesai.

Aturan paling penting saat mengintegrasikan dengan API: jangan pernah mencoba mengambil atau menggunakan URL hasil sampai status tugas adalah SUCCEEDED. Membaca hasil saat tugas masih PENDING atau IN_PROGRESS adalah penyebab paling umum dari laporan "kesalahan saat mengambil model".

Polling berarti memanggil endpoint "get task" berulang kali untuk ID tugas Anda hingga mencapai status terminal (SUCCEEDED, FAILED, atau CANCELED). Loop polling sederhana tampak 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 adalah interval yang umum.

• Periksa field status pada setiap respons. Terus lakukan polling selama nilainya PENDING atau IN_PROGRESS.

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

• Tambahkan batas waktu/jumlah percobaan maksimum yang wajar di klien Anda agar tugas yang macet tidak melakukan polling selamanya.

Polling sederhana dan cocok untuk skrip, tugas batch, dan integrasi bervolume rendah. Untuk integrasi bervolume tinggi atau yang sensitif terhadap latensi, webhook biasanya lebih cocok.

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

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

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

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

• Saat menerimanya, cari detail tugas lengkap berdasarkan id melalui API alih-alih hanya memercayai isi webhook, untuk memastikan Anda mendapatkan hasil yang otoritatif dan terbaru.

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

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

• Sebuah webhook dapat dikirimkan lebih dari sekali untuk tugas yang sama (percobaan ulang di sisi pengirim, duplikasi jaringan, dll.).

• Loop polling dan pengendali webhook mungkin keduanya mencoba memproses tugas yang sama yang sudah selesai jika keduanya berjalan.

Untuk tetap idempoten, kunci logika pemrosesan Anda pada id tugas — misalnya, periksa apakah Anda sudah menyimpan/mengunduh hasil untuk id tersebut sebelum melakukannya lagi, dan buat "tandai sebagai diproses" sebagai satu langkah atom dalam basis data Anda sendiri.

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

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

• Jangan mengandalkan progress saja — selalu periksa status juga, karena progress dapat sementara 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 dapat mengambil model saya" berawal dari salah satu penyebab berikut:

• Mengambil terlalu awal. Memanggil URL hasil, atau membaca kolom model, sebelum status adalah SUCCEEDED. Ini adalah penyebab yang paling sering terjadi.

• Aset kedaluwarsa. Menunggu terlalu lama setelah SUCCEEDED untuk mengunduh — URL hasil berhenti bekerja setelah jangka waktu retensi untuk jenis tugas tersebut berakhir.

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

• Memperlakukan FAILED sebagai status sementara dan terus-menerus melakukan polling pada tugas yang sudah gagal alih-alih mengajukan ulang.

• Masalah jaringan/waktu habis antara server Anda dan Meshy yang disalahartikan sebagai masalah generasi.

Jika hasil generasi tidak sesuai ekspektasi Anda, atau permintaan gagal sepenuhnya, perhatikan hal-hal berikut:

• Meshy API saat ini belum mendukung percobaan ulang tugas yang sudah ada secara langsung — untuk mencoba lagi, kirim permintaan generasi baru, yang akan menggunakan kredit seperti biasa.

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

• Untuk polling itu sendiri, coba ulang panggilan "get task" saat terjadi kesalahan jaringan sementara, tetapi jangan menganggap satu polling yang gagal sebagai kegagalan generasi — percayai field status hanya setelah Anda mendapatkan respons yang berhasil.

• Jika Anda memerlukan fungsi percobaan ulang bawaan untuk generasi, hubungi tim penjualan Meshy tentang opsi paket enterprise.

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

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

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

Beralihlah ke polling tugas berdasarkan id secara langsung. Pastikan juga endpoint Anda dapat dijangkau 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 mengirim permintaan generasi baru, yang akan memakai kredit seperti biasa. Hubungi tim sales untuk opsi enterprise jika Anda memerlukan dukungan percobaan ulang bawaan.

File hasil hanya disimpan di server Meshy selama waktu terbatas setelah tugas selesai, jadi segera unduh keluaran ke penyimpanan Anda sendiri begitu tugas berhasil, jangan menunggu.