Meshy API Webhooks vs Polling: Bila Hasil Sedia

Tugasan penjanaan Meshy API (Text to 3D, Image to 3D, Rigging dan banyak lagi) berjalan secara tak segerak — anda menghantar tugasan dan kemudian perlu mengetahui bila ia siap sebelum mendapatkan hasilnya. Artikel ini menerangkan kitaran hayat tugasan dan dua cara yang disokong untuk mengetahui bila tugasan telah selesai: polling dan webhooks — serta cara mengelakkan isu "errors retrieving the model" yang paling biasa.

Setiap tugasan penjanaan melalui satu set keadaan yang kecil, dipulangkan dalam medan status objek tugasan:

• PENDING — tugasan telah dimasukkan ke dalam baris gilir tetapi pemprosesan belum bermula.

• IN_PROGRESS — tugasan sedang diproses secara aktif. Medan progress (0-100) meningkat apabila kerja selesai dilakukan.

• SUCCEEDED — tugasan selesai dengan jayanya dan progress ialah 100. URL hasil (fail model, tekstur, pratonton) kini tersedia dalam respons.

• FAILED — tugasan tidak dapat diselesaikan. Kredit untuk tugasan yang gagal akan dikembalikan secara automatik.

• CANCELED — tugasan dibatalkan sebelum selesai.

Peraturan paling penting semasa berintegrasi dengan API: jangan sesekali cuba mendapatkan atau menggunakan URL hasil sehingga status tugasan ialah SUCCEEDED. Membaca hasil semasa tugasan masih PENDING atau IN_PROGRESS adalah punca paling biasa laporan "errors retrieving the model".

Polling bermaksud memanggil endpoint "dapatkan tugasan" secara berulang kali untuk ID tugasan anda sehingga ia mencapai keadaan terminal (SUCCEEDED, FAILED, atau CANCELED). Gelung polling yang mudah kelihatan seperti berikut:

• Hantar permintaan penjanaan dan simpan id tugasan yang dipulangkan.

• Panggil endpoint "retrieve task" yang sepadan (contohnya, endpoint task-by-id Text to 3D atau Image to 3D) pada selang waktu tertentu — beberapa saat adalah biasa.

• Semak medan status pada setiap respons. Teruskan polling selagi ia PENDING atau IN_PROGRESS.

• Berhenti polling sebaik sahaja status ialah SUCCEEDED (baca URL hasil), FAILED, atau CANCELED.

• Tambahkan had timeout/cubaan maksimum yang munasabah dalam klien anda supaya tugasan yang tersekat tidak di-poll selama-lamanya.

Polling adalah mudah dan berkesan untuk skrip, kerja batch dan integrasi volum rendah. Untuk integrasi volum tinggi atau sensitif kependatan, webhook biasanya lebih sesuai.

Daripada bertanya berulang kali "dah siap ke belum?", anda boleh meminta Meshy memaklumkan pelayan anda pada saat tugasan selesai. Untuk menggunakan webhook:

• Konfigurasikan URL webhook (callback) yang boleh dicapai oleh Meshy — ini biasanya ditetapkan pada tahap tetapan akaun/API atau dihantar sebagai parameter pada permintaan penjanaan, bergantung pada endpoint.

• Pastikan endpoint anda boleh dicapai secara awam melalui HTTPS dan membalas dengan pantas (pulangkan status 2xx dengan segera, kemudian proses payload secara tak segerak).

• Apabila tugasan mencapai keadaan terminal, Meshy menghantar payload ke endpoint anda yang mengandungi id tugasan dan status akhirnya.

• Setelah diterima, semak butiran penuh tugasan melalui id menggunakan API dan bukannya mempercayai badan webhook semata-mata, untuk memastikan anda mempunyai hasil yang sahih dan terkini.

Webhook mengurangkan panggilan API yang tidak perlu dan memberikan anda pemberitahuan hampir segera, tetapi anda masih perlu mengekalkan fallback polling berkala untuk tugasan yang penghantaran webhooknya mungkin terlepas atau tertangguh (contohnya disebabkan masalah rangkaian sementara di pihak anda).

Sama ada anda menggunakan polling atau webhook, kod pengendalian hasil anda harus bersifat idempoten — selamat untuk dijalankan lebih dari sekali untuk tugasan yang sama tanpa kesan sampingan. Ini penting kerana:

• Satu webhook mungkin dihantar lebih dari sekali untuk tugasan yang sama (cubaan semula di pihak penghantar, penduplikasi rangkaian, dll.).

• Gelung polling dan pengendali webhook mungkin kedua-duanya cuba memproses tugasan yang sama yang telah selesai jika kedua-duanya sedang berjalan.

Untuk kekal idempoten, jadikan id tugasan sebagai kunci logik pemprosesan anda — contohnya, semak sama ada anda telah menyimpan/memuat turun hasil untuk id tersebut sebelum melakukannya semula, dan jadikan "tanda sebagai diproses" sebagai satu langkah atom dalam pangkalan data anda sendiri.

Respons dengan "status": "SUCCEEDED" dan "progress": 100 adalah satu-satunya isyarat yang menjamin payload hasil (URL model, tekstur, lakaran kecil) lengkap dan selamat digunakan. Secara konkrit, dalam kod anda:

• Sahkan status === "SUCCEEDED" sebelum membaca apa-apa daripada medan URL result/model.

• Jangan bergantung pada progress semata-mata — sentiasa semak status juga, kerana progress boleh menunjukkan nilai tinggi sekejap sahaja sebelum tugasan dimuktamadkan sepenuhnya.

• Muat turun fail hasil dengan segera sebaik sahaja SUCCEEDED — aset yang dijana hanya disimpan pada pelayan Meshy untuk tempoh terhad, selepas itu URL tidak akan lagi boleh diakses.

Kebanyakan laporan "saya tidak boleh mendapatkan model saya" dapat dijejak kepada salah satu punca berikut:

• Mendapatkan hasil terlalu awal. Memanggil URL hasil, atau membaca medan model, sebelum status ialah SUCCEEDED. Ini jauh merupakan punca yang paling kerap.

• Aset telah tamat tempoh. Menunggu terlalu lama selepas SUCCEEDED untuk memuat turun — URL hasil berhenti berfungsi selepas tempoh pengekalan bagi jenis tugasan tersebut telah berlalu.

• Menggunakan ID tugasan yang usang atau salah — contohnya, menggunakan semula ID daripada permintaan terdahulu yang tidak berkaitan.

• Menganggap FAILED sebagai keadaan sementara dan terus menge-poll tugasan yang telah gagal dan bukannya menghantar semula.

• Masalah rangkaian/timeout antara pelayan anda dan Meshy yang disalahanggap sebagai masalah penjanaan.

Jika penjanaan tidak memenuhi jangkaan anda, atau permintaan gagal sepenuhnya, ingat perkara berikut:

• Meshy API buat masa ini tidak menyokong mencuba semula tugasan sedia ada secara terus — untuk mencuba lagi, hantar permintaan penjanaan baharu, yang akan menggunakan kredit seperti biasa.

• Untuk kegagalan rangkaian sementara semasa memanggil API (timeout, respons 5xx), backoff eksponen yang singkat sebelum menghantar semula permintaan adalah munasabah.

• Untuk polling itu sendiri, cuba semula panggilan "dapatkan tugasan" atas ralat rangkaian sementara, tetapi jangan anggap satu kegagalan poll sebagai kegagalan penjanaan — hanya percayai medan status setelah anda mendapat respons yang berjaya.

• Jika anda memerlukan fungsi cuba semula terbina dalam untuk penjanaan, hubungi pasukan jualan Meshy mengenai pilihan pelan perusahaan.

Ini hampir selalu berlaku kerana kod cuba membaca hasil sebelum tugasan selesai. Sentiasa sahkan status ialah SUCCEEDED (dan progress ialah 100) sebelum mendapatkan URL model.

Polling lebih mudah disediakan dan sesuai untuk skrip volum rendah atau sekali guna. Webhook lebih baik untuk integrasi pengeluaran dengan banyak tugasan serentak, kerana ia mengelakkan permintaan berulang yang tidak perlu dan memaklumkan anda dengan segera apabila tugasan selesai.

Uruskannya secara idempoten — semak id tugasan dengan apa yang telah anda proses, dan langkau pemprosesan semula jika ia telah dikendalikan.

Kembali kepada polling tugasan secara terus melalui id. Juga sahkan endpoint anda boleh dicapai secara awam melalui HTTPS dan memulangkan respons 2xx dengan pantas, kerana endpoint yang perlahan atau tidak boleh dicapai boleh menyebabkan masalah penghantaran.

Buat masa ini tidak — anda perlu menghantar permintaan penjanaan baharu, yang menggunakan kredit seperti biasa. Hubungi jualan mengenai pilihan perusahaan jika anda memerlukan sokongan cuba semula terbina dalam.

Fail hasil hanya disimpan pada pelayan Meshy untuk tempoh terhad selepas tugasan selesai, jadi muat turun output ke storan anda sendiri sebaik sahaja tugasan berjaya dan bukannya menunggu.

• Mengapa Saya Sentiasa Menghadapi Ralat Semasa Mendapatkan Model daripada Hasil Penjanaan Menggunakan API?