Webhook vs Polling Meshy API: Apabila Hasil Sedia

Tugasan penjanaan Meshy API (Text to 3D, Image to 3D, Rigging dan lain-lain) berjalan secara tak segerak — anda menghantar tugasan dan kemudian perlu mengetahui bila ia selesai sebelum mengambil hasilnya. Artikel ini menerangkan kitaran hayat tugasan dan dua cara yang disokong untuk mengetahui bila sesuatu tugasan telah selesai: polling dan webhook — serta cara mengelakkan isu "ralat mendapatkan semula model" yang paling biasa.

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

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

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

• 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 dikembalikan secara automatik.

• CANCELED — tugasan telah dibatalkan sebelum selesai.

Peraturan paling penting sekali apabila berintegrasi dengan API: jangan sekali-kali cuba mengambil atau menggunakan URL hasil sehingga status tugasan ialah SUCCEEDED. Membaca hasil semasa tugasan masih PENDING atau IN_PROGRESS ialah punca paling biasa bagi laporan "ralat semasa mengambil model".

Polling bermaksud memanggil berulang kali titik akhir "get task" untuk ID tugasan anda sehingga ia mencapai keadaan terminal (SUCCEEDED, FAILED atau CANCELED). Gelung polling yang mudah kelihatan seperti ini:

• Hantar permintaan penjanaan dan simpan id tugasan yang dikembalikan.

• Panggil titik akhir "retrieve task" yang berkaitan (contohnya, titik akhir task-by-id Text to 3D atau Image to 3D) pada selang waktu — beberapa saat ialah tempoh biasa.

• Semak medan status pada setiap respons. Teruskan polling semasa nilainya PENDING atau IN_PROGRESS.

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

• Tambah had masa tamat/percubaan maksimum yang munasabah dalam klien anda supaya tugasan yang tersekat tidak melakukan polling selama-lamanya.

Polling adalah mudah dan berfungsi dengan baik untuk skrip, kerja kelompok dan integrasi volum rendah. Untuk integrasi volum tinggi atau sensitif kependaman, webhook biasanya lebih sesuai.

Daripada berulang kali bertanya "sudah siapkah ia?", anda boleh meminta Meshy memberitahu pelayan anda sebaik sahaja sesuatu tugasan selesai. Untuk menggunakan webhook:

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

• Pastikan endpoint anda boleh dicapai secara awam melalui HTTPS dan bertindak balas dengan pantas (kembalikan status 2xx serta-merta, kemudian proses muatan secara tak segerak).

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

• Selepas menerimanya, cari butiran penuh tugasan melalui id menggunakan API dan jangan hanya bergantung pada badan webhook semata-mata, untuk memastikan anda memperoleh keputusan terkini yang sahih.

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

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

• Webhook mungkin dihantar lebih daripada sekali untuk tugasan yang sama (cubaan semula di pihak penghantar, pertindihan rangkaian, dsb.).

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

Untuk kekal idempoten, asaskan logik pemprosesan anda pada id tugasan — sebagai contoh, semak sama ada anda sudah menyimpan/memuat turun hasil untuk id itu sebelum melakukannya sekali lagi, dan jadikan “tandakan sebagai diproses” sebagai satu langkah atomik tunggal dalam pangkalan data anda sendiri.

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

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

• Jangan bergantung pada progress sahaja — sentiasa semak status juga, kerana kemajuan boleh menunjukkan nilai tinggi secara sementara sebelum tugasan dimuktamadkan sepenuhnya.

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

Kebanyakan laporan "Saya tidak dapat mengambil model saya" berpunca daripada salah satu punca berikut:

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

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

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

• Menganggap FAILED sebagai keadaan sementara dan terus melakukan polling pada tugasan yang telah gagal daripada menyerahkannya semula.

• Isu rangkaian/timeout antara pelayan anda dan Meshy yang disalah tafsir sebagai masalah penjanaan.

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

• Meshy API pada masa ini tidak menyokong cubaan semula tugasan sedia ada di tempatnya — untuk mencuba lagi, hantar permintaan penjanaan baharu, yang akan menggunakan kredit seperti biasa.

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

• Untuk polling itu sendiri, cuba semula panggilan "get task" apabila ralat rangkaian sementara berlaku, tetapi jangan anggap satu polling yang gagal sebagai kegagalan penjanaan — hanya percayai medan status apabila anda menerima respons yang berjaya.

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

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

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

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

Beralih kepada polling tugasan melalui id secara terus. Juga pastikan titik akhir anda boleh dicapai secara awam melalui HTTPS dan mengembalikan respons 2xx dengan pantas, kerana titik akhir 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 pasukan jualan tentang pilihan perusahaan jika anda memerlukan sokongan cubaan 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 daripada menunggu.