lowpoly sera retiré le 30 oct. 2026. meshy-7 sera retiré en tant que modèle de génération 3D le 31 déc. 2026 ; il reste disponible en tant que modèle de texture. Changez de modèle avant ces dates pour éviter les erreurs de requête. Voir toutes les dépréciations

Webhooks

Demandez à Meshy d'envoyer une requête POST à votre serveur lorsqu'une tâche de l'API progresse ou se termine, afin que vous n'ayez pas besoin d'interroger l'API.


Pourquoi utiliser les webhooks

Les webhooks demandent moins de travail et coûtent moins cher que l'interrogation de l'API pour connaître le statut de chaque tâche. Meshy envoie chaque mise à jour au fur et à mesure qu'elle se produit, vous la recevez donc plus tôt, et les webhooks s'adaptent mieux à la montée en charge que l'interrogation. Vous envoyez également moins de requêtes, ce qui vous éloigne de vos limites de débit.


Configurer un webhook

Pour ajouter un webhook, suivez ces étapes :

  1. Ouvrez la page Webhooks dans la Developer Platform, puis cliquez sur Create Webhook.
  2. Dans Payload URL, saisissez l'URL qui recevra les livraisons. Meshy ne livre que via https://.
  3. Conservez une copie du Webhook Secret que la boîte de dialogue remplit automatiquement. Chaque livraison le porte, afin que votre serveur puisse vérifier qu'une requête provient bien de Meshy. Pour un webhook que vous possédez déjà, cliquez sur l'icône en forme d'œil dans sa colonne Secret pour le voir.
  4. Sélectionnez Active, puis cliquez sur Confirm.

Chaque compte peut avoir 5 webhooks actifs, et 10 au total. Chaque webhook actif reçoit les mises à jour de statut de toutes vos tâches API.

Pour tester un webhook avec un serveur sur votre ordinateur, consultez Tester sur votre ordinateur.


Traiter une livraison

Pour accepter une livraison, répondez avec un statut inférieur à 400, comme 200 ou 202. Meshy attend environ 25 secondes la réponse, alors enregistrez d'abord la livraison et répondez en premier. Effectuez ensuite le travail plus long, comme le téléchargement du modèle.

Un statut de 400 ou plus, ou une absence de réponse, est considéré comme une livraison échouée. Meshy la relance avec des délais de plus en plus longs entre les tentatives, jusqu'à 4 fois pour une mise à jour IN_PROGRESS et jusqu'à 9 fois pour un statut final. Si 20 mises à jour consécutives échouent à chaque tentative, Meshy peut désactiver le webhook. Pour le réactiver, modifiez-le sur la page Webhooks et sélectionnez Active.

Écrivez votre code en tenant compte des cas suivants :

  • Les livraisons peuvent arriver dans le désordre. Une livraison IN_PROGRESS peut arriver après la livraison finale, alors ne la laissez pas remplacer un statut final.
  • La même mise à jour peut arriver plus d'une fois. Traitez chaque paire id et status une seule fois.
  • Toute personne qui connaît votre URL peut lui envoyer une requête. Comparez X-MESHY-API-WEBHOOK-SECRET-KEY avec votre copie du secret, et rejetez toute requête qui ne correspond pas.

Si la livraison finale d'une tâche n'est pas arrivée après environ le double de la durée habituelle de la tâche, récupérez la tâche depuis son point de terminaison GET. Pour les durées habituelles et le temps d'attente, consultez Cycle de vie d'une tâche.


Tester sur votre ordinateur

Meshy ne livre qu'à une URL publique https://, elle ne peut donc pas atteindre directement un serveur sur votre ordinateur. Pour tester du code sur votre ordinateur, redirigez une URL publique vers celui-ci avec un proxy webhook. Ces étapes utilisent smee.io, et tout service de proxy webhook fonctionne de la même manière.

  1. Ouvrez smee.io et cliquez sur Start a new channel. Copiez l'URL sous Webhook Proxy URL.

  2. Si vous n'avez pas encore le client smee, installez-le :

    npm install --global smee-client
    
  3. Redirigez le canal vers votre serveur. Remplacez WEBHOOK_PROXY_URL par votre URL du proxy webhook :

    smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
    

    La sortie ressemble à ceci, où WEBHOOK_PROXY_URL est votre URL du proxy webhook :

    Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
    Connected WEBHOOK_PROXY_URL
    

    Laissez-le fonctionner pendant vos tests. Pour arrêter la redirection, appuyez sur Ctrl+C. Votre serveur reçoit les livraisons sur le port 3000 au chemin /webhook, configurez donc votre code pour écouter à cet endroit.

  4. Sur la page Webhooks, créez un webhook avec l'URL du proxy webhook comme Payload URL.


Charge utile de livraison

Meshy envoie une livraison pendant qu'une tâche est IN_PROGRESS, et une autre lorsque la tâche atteint un statut final. Une tâche peut atteindre son statut final sans livraison IN_PROGRESS.

Chaque livraison est une requête POST vers votre URL de payload avec les en-têtes suivants :

En-têteValeur
X-MESHY-API-WEBHOOK-SECRET-KEYLe secret du webhook
X-MESHY-API-WEBHOOK-USER-IDL'ID de l'utilisateur Meshy propriétaire du webhook
Meshy-Webhook-Versionv1, le format du corps
Content-Typeapplication/json
User-AgentMeshyAPIWebhook/1.0.0

Le corps JSON est l'objet tâche. C'est le même objet que celui renvoyé par le point de terminaison GET de la tâche, à l'exception de progress. Une livraison envoie progress comme l'une de ces valeurs :

  • 50 pendant que la tâche est IN_PROGRESS
  • 100 lorsque la tâche réussit
  • 0 lorsque la tâche échoue ou est annulée

Pour les champs de chaque objet tâche, avec un exemple, consultez les sections suivantes :