Meshy API : webhooks ou polling, quand les résultats sont prêts

Les tâches de génération de l'API Meshy (Text to 3D, Image to 3D, Rigging, et plus encore) s'exécutent de manière asynchrone — vous soumettez une tâche, puis 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 la façon d'éviter le problème le plus courant d'« erreurs lors de la récupération du modèle ».

Chaque tâche de génération passe par un petit ensemble d'états, renvoyés dans le champ status de l'objet 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 progresse.

• SUCCEEDED — la tâche s'est terminée avec succès et progress vaut 100. Les URL des résultats (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 son achèvement.

La règle la plus importante lors de l'intégration de l'API : ne jamais tenter de récupérer ou d'utiliser les URL de résultats tant que le status de la tâche n'est pas SUCCEEDED. Lire les résultats alors qu'une tâche est encore PENDING ou IN_PROGRESS est la cause la plus fréquente des signalements d'« erreurs de récupération du modèle ».

Le polling consiste à appeler de manière répétée le point de terminaison « get task » pour votre ID de tâche jusqu'à ce qu'elle atteigne un état terminal (SUCCEEDED, FAILED ou CANCELED). Une boucle de polling simple se présente comme suit :

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

• Appelez le point de terminaison « retrieve task » correspondant (par exemple, le point de terminaison Text to 3D ou Image to 3D par ID de tâche) à intervalle régulier — quelques secondes est typique.

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

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

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

Le polling est simple et adapté aux scripts, aux tâches par lots et aux intégrations à faible volume. Pour les intégrations à volume élevé ou sensibles à la latence, un webhook est généralement plus adapté.

Au lieu de demander sans cesse « est-ce terminé ? », 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/de l'API ou transmise en tant que paramètre dans la requête de génération, selon le point de terminaison.

• Assurez-vous que votre point de terminaison est accessible publiquement via HTTPS et répond rapidement (renvoyez immédiatement un statut 2xx, puis traitez la charge utile de manière asynchrone).

• Lorsque la tâche atteint un état terminal, Meshy envoie à votre point de terminaison une charge utile 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 devez tout de même conserver un repli de polling périodique pour les tâches pour lesquelles une livraison de webhook pourrait être manquée ou retardée (par exemple en raison d'un problème réseau transitoire de votre côté).

Que vous utilisiez le polling ou les webhooks, votre code de traitement des résultats doit être idempotent — 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 s'exécutent tous les deux.

Pour rester idempotent, faites reposer 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 recommencer, 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 qui garantit que la charge utile du résultat (URL des modèles, textures, vignettes) est complète et peut être utilisée en toute sécurité. 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 aussi status, car la progression peut brièvement afficher des valeurs élevées avant que la tâche ne soit totalement finalisée.

• Téléchargez rapidement les fichiers de résultat une fois SUCCEEDED — les ressources générées ne sont conservées 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 « je n'arrive 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 ne 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 propre à ce type de tâche dépassée.

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

• Traiter FAILED comme un état transitoire et continuer à interroger une tâche déjà échouée au lieu de la soumettre à nouveau.

• Problèmes de réseau ou de délai d'attente 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 purement et simplement, gardez les points suivants à l'esprit :

• L'API Meshy ne permet pas actuellement de relancer une tâche existante sur place — pour réessayer, soumettez une nouvelle demande de génération, qui consommera normalement des crédits.

• En cas de défaillance réseau transitoire lors de l'appel à l'API (délais d'attente, réponses 5xx), un court backoff exponentiel avant de resoumettre la requête est raisonnable.

• Pour le polling lui-même, relancez l'appel « get task » en cas d'erreur réseau transitoire, mais ne considérez pas un seul échec de polling comme un échec de génération — ne vous fiez au champ status qu'une fois que vous avez obtenu une réponse réussie.

• Si vous avez besoin d'une fonctionnalité de nouvelle tentative intégrée pour les générations, contactez l'équipe commerciale de Meshy au sujet des options du 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. Vérifiez toujours que status vaut SUCCEEDED (et que progress vaut 100) avant de récupérer les URL des modèles.

Le polling est plus simple à mettre en place et convient aux scripts ponctuels ou à faible volume. Les webhooks sont mieux adaptés aux intégrations de production comportant de nombreuses tâches simultanées, car ils évitent les requêtes répétées inutiles et vous notifient immédiatement lorsqu'une tâche est terminée.

Le traiter de manière idempotente : vérifiez l'id de la tâche par rapport à ce que vous avez déjà traité, et ignorez le nouveau traitement si elle a déjà été prise en charge.

Repassez au polling de la tâche par son id directement. Vérifiez également que votre point de terminaison est accessible publiquement en HTTPS et renvoie rapidement une réponse 2xx, car des points de terminaison lents ou inaccessibles peuvent provoquer des problèmes de livraison.

Pas pour le moment — vous devrez soumettre une nouvelle demande de génération, ce qui consomme normalement des crédits. Contactez le service commercial au sujet des options entreprise si vous avez besoin d'une prise en charge intégrée des nouvelles tentatives.

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 réussit, sans attendre.