Webhooks vs polling de l'API Meshy : quand les résultats sont-ils prêts ?

Les tâches de génération de l'API Meshy (Text to 3D, Image to 3D, Rigging, etc.) s'exécutent de manière asynchrone — vous soumettez une tâche, puis vous devez déterminer quand elle est terminée avant de récupérer le résultat. Cet article explique le cycle de vie des tâches et les deux méthodes prises en charge pour savoir quand une tâche est terminée : le polling et les webhooks — ainsi que comment éviter l'erreur la plus fréquente, « errors retrieving the model ».

Chaque tâche de génération passe par un petit ensemble d'états, renvoyés dans le champ status de l'objet de tâche :

• PENDING — la tâche a été mise en file d'attente, mais le traitement n'a pas encore commencé.

• IN_PROGRESS — la tâche est en cours de traitement. Le champ progress (0-100) augmente à mesure que le travail avance.

• SUCCEEDED — la tâche s'est terminée avec succès et progress est à 100. Les URL de résultat (fichiers de modèle, textures, aperçus) sont désormais disponibles dans la réponse.

• FAILED — la tâche n'a pas pu aboutir. Les crédits des tâches échouées sont automatiquement remboursés.

• CANCELED — la tâche a été annulée avant d'être terminée.

La règle la plus importante lors de l'intégration avec l'API : n'essayez jamais de récupérer ou d'utiliser les URL de résultat tant que le status de la tâche n'est pas SUCCEEDED. Lire les résultats alors que la tâche est encore PENDING ou IN_PROGRESS est la cause la plus fréquente des signalements d'« errors retrieving the model ».

Le polling consiste à appeler répétitivement l'endpoint « get task » pour l'ID de votre tâche jusqu'à ce qu'elle atteigne un état final (SUCCEEDED, FAILED ou CANCELED). Une simple boucle de polling ressemble à ceci :

• Soumettez la requête de génération et stockez l'id de tâche renvoyé.

• Appelez l'endpoint « retrieve task » correspondant (par exemple, l'endpoint Text to 3D ou Image to 3D task-by-id) à intervalles réguliers — quelques secondes est typique.

• Vérifiez le champ status à chaque réponse. Continuez le polling tant qu'il s'agit de PENDING ou IN_PROGRESS.

• Arrêtez le polling dès que status est SUCCEEDED (lisez les URL de résultat), FAILED ou CANCELED.

• Ajoutez dans votre client une garde raisonnable de timeout/nombre maximal de tentatives afin qu'une tâche bloquée ne fasse pas tourner le polling indéfiniment.

Le polling est simple et fonctionne bien pour les scripts, les traitements par lots et les intégrations à faible volume. Pour les intégrations à fort volume ou sensibles à la latence, un webhook est généralement un meilleur choix.

Au lieu de demander répétitivement « est-ce que c'est fini ? », vous pouvez demander à Meshy de notifier votre serveur dès qu'une tâche se termine. Pour utiliser les webhooks :

• Configurez une URL de webhook (callback) que Meshy peut atteindre — elle est généralement définie au niveau des paramètres du compte/API ou transmise en paramètre de la requête de génération, selon l'endpoint.

• Assurez-vous que votre endpoint est publiquement accessible en HTTPS et qu'il répond rapidement (renvoyez immédiatement un statut 2xx, puis traitez le payload de manière asynchrone).

• Lorsque la tâche atteint un état final, Meshy envoie un payload à votre endpoint contenant l'id de la tâche et son status final.

• À la réception, récupérez les détails complets de la tâche par id via l'API plutôt que de vous fier uniquement au corps du webhook, afin de vous assurer de disposer du résultat faisant autorité et à jour.

Les webhooks réduisent les appels API inutiles et vous offrent une notification quasi instantanée, mais vous devriez tout de même conserver une solution de repli par polling périodique pour les tâches où une livraison de webhook risque d'être manquée ou retardée (par exemple en raison d'un problème réseau temporaire de votre côté).

Que vous utilisiez le polling ou les webhooks, votre code de traitement des résultats doit être idempotent — c'est-à-dire pouvoir s'exécuter plusieurs fois pour la même tâche sans effets de bord. C'est important car :

• Un webhook peut être livré plus d'une fois pour la même tâche (nouvelles tentatives côté expéditeur, duplication réseau, etc.).

• Une boucle de polling et un gestionnaire de webhook peuvent tous deux tenter de traiter la même tâche terminée s'ils tournent simultanément.

Pour rester idempotent, basez votre logique de traitement sur l'id de la tâche — par exemple, vérifiez si vous avez déjà stocké/téléchargé les résultats pour cet id avant de le refaire, et faites de « marquer comme traité » une étape atomique unique dans votre propre base de données.

Une réponse avec "status": "SUCCEEDED" et "progress": 100 est le seul signal garantissant que le payload de résultat (URL de modèle, textures, miniatures) est complet et sûr à utiliser. Concrètement, dans votre code :

• Vérifiez status === "SUCCEEDED" avant de lire quoi que ce soit dans les champs result/URL de modèle.

• Ne vous fiez pas uniquement à progress — vérifiez toujours également status, car le progress peut brièvement afficher des valeurs élevées avant que la tâche ne soit entièrement finalisée.

• Téléchargez rapidement les fichiers de résultat une fois SUCCEEDED atteint — les assets générés ne sont conservés sur les serveurs de Meshy que pendant une durée limitée, après quoi les URL ne seront plus résolues.

La plupart des signalements du type « je ne peux pas récupérer mon modèle » remontent à l'une des causes suivantes :

• Récupération trop précoce. Appeler l'URL de résultat, ou lire les champs du modèle, avant que status soit SUCCEEDED. C'est de loin la cause la plus fréquente.

• Assets expirés. Attendre trop longtemps après SUCCEEDED pour télécharger — les URL de résultat cessent de fonctionner une fois la fenêtre de rétention pour ce type de tâche écoulée.

• Utilisation d'un ID de tâche obsolète ou erroné — par exemple, réutiliser un ID d'une requête précédente sans lien.

• Considérer FAILED comme un état temporaire et continuer à effectuer le polling d'une tâche déjà échouée au lieu de la soumettre à nouveau.

• Problèmes réseau/timeout entre votre serveur et Meshy, interprétés à tort comme un problème de génération.

Si une génération ne répond pas à vos attentes, ou si une requête échoue carrément, gardez à l'esprit ce qui suit :

• L'API Meshy ne prend actuellement pas en charge la relance d'une tâche existante en place — pour réessayer, soumettez une nouvelle requête de génération, qui consommera normalement des crédits.

• En cas d'échec réseau temporaire lors de l'appel de l'API (timeouts, réponses 5xx), un court backoff exponentiel avant de soumettre à nouveau la requête est raisonnable.

• Pour le polling lui-même, retentez l'appel « get task » en cas d'erreurs réseau temporaires, mais ne considérez pas un seul échec de polling comme un échec de génération — ne vous fiez au champ status qu'après avoir reçu une réponse réussie.

• Si vous avez besoin d'une fonctionnalité de relance intégrée pour les générations, contactez l'équipe commerciale de Meshy au sujet des options de plan entreprise.

Cela se produit presque toujours parce que le code tente de lire le résultat avant que la tâche ne soit terminée. Confirmez toujours que status est SUCCEEDED (et progress est à 100) avant de récupérer les URL du modèle.

Le polling est plus simple à mettre en place et convient parfaitement aux scripts à faible volume ou ponctuels. Les webhooks sont préférables pour les intégrations de production avec de nombreuses tâches concurrentes, car ils évitent les requêtes répétées inutiles et vous notifient immédiatement dès qu'une tâche se termine.

Traitez-le de manière idempotente — vérifiez l'id de la tâche par rapport à ce que vous avez déjà traité, et ignorez le retraitement s'il a déjà été géré.

Repliez-vous sur le polling de la tâche directement par id. Vérifiez également que votre endpoint est publiquement accessible en HTTPS et renvoie rapidement une réponse 2xx, car des endpoints lents ou inaccessibles peuvent provoquer des problèmes de livraison.

Pas pour le moment — vous devrez soumettre une nouvelle requête de génération, qui consommera normalement des crédits. Contactez l'équipe commerciale au sujet des options entreprise si vous avez besoin d'une prise en charge de relance intégrée.

Les fichiers de résultat ne sont conservés sur les serveurs de Meshy que pendant une durée limitée après la fin d'une tâche ; téléchargez donc les sorties vers votre propre stockage dès que la tâche aboutit plutôt que d'attendre.

• Pourquoi rencontre-je systématiquement des erreurs lors de la récupération des modèles depuis un résultat de génération via l'API ?