lowpoly se retira el 30 oct 2026. meshy-7 se retira como modelo de generación 3D el 31 dic 2026; como modelo de texturas sigue disponible. Cambia de modelo antes de estas fechas para evitar errores en las solicitudes. Ver todas las obsolescencias

Webhooks

Haz que Meshy envíe una solicitud POST a tu servidor cuando una tarea de la API avance o finalice, para que no tengas que hacer sondeos (polling).


Por qué usar webhooks

Los webhooks requieren menos trabajo y cuestan menos que sondear la API para conocer el estado de cada tarea. Meshy envía cada actualización en el momento en que ocurre, de modo que la recibes antes, y los webhooks escalan mejor que el sondeo. Además, envías menos solicitudes, lo que te mantiene más alejado de tus límites de tasa.


Configurar un webhook

Para añadir un webhook, sigue estos pasos:

  1. Abre la página de Webhooks en la Developer Platform, y haz clic en Create Webhook.
  2. En Payload URL, introduce la URL que recibirá las entregas. Meshy solo entrega a través de https://.
  3. Guarda una copia del Webhook Secret que el diálogo completa. Cada entrega lo incluye, para que tu servidor pueda comprobar que una solicitud proviene de Meshy. Para un webhook que ya tengas, haz clic en el icono del ojo en su columna Secret para verlo.
  4. Selecciona Active, y haz clic en Confirm.

Cada cuenta puede tener 5 webhooks activos, y 10 en total. Cada webhook activo recibe las actualizaciones de estado de todas tus tareas de la API.

Para probar un webhook con un servidor en tu computadora, consulta Probar en tu computadora.


Gestionar una entrega

Para aceptar una entrega, responde con un estado inferior a 400, como 200 o 202. Meshy espera unos 25 segundos la respuesta, así que almacena la entrega y responde primero. Realiza el trabajo lento después, como descargar el modelo.

Un estado de 400 o superior, o la ausencia de respuesta, cuenta como una entrega fallida. Meshy la reintenta con esperas cada vez más largas entre intentos, hasta 4 veces para una actualización IN_PROGRESS y hasta 9 veces para un estado final. Si 20 actualizaciones seguidas fallan en todos los intentos, Meshy puede desactivar el webhook. Para volver a activarlo, edítalo en la página de Webhooks y selecciona Active.

Escribe tu código para estos casos:

  • Las entregas pueden llegar desordenadas. Una entrega IN_PROGRESS puede llegar después de la final, así que no dejes que reemplace un estado final.
  • La misma actualización puede llegar más de una vez. Gestiona cada par de id y status una sola vez.
  • Cualquiera que conozca tu URL puede enviarle una solicitud. Compara X-MESHY-API-WEBHOOK-SECRET-KEY con tu copia del secreto, y rechaza una solicitud que no coincida.

Si la entrega final de una tarea no ha llegado después de aproximadamente el doble de su tiempo habitual, obtén la tarea desde su endpoint GET. Para conocer los tiempos habituales y cuánto esperar, consulta Ciclo de vida de la tarea.


Probar en tu computadora

Meshy solo entrega a una URL pública https://, por lo que no puede llegar directamente a un servidor en tu computadora. Para probar código en tu computadora, reenvía una URL pública hacia él con un proxy de webhook. Estos pasos usan smee.io, y cualquier servicio de proxy de webhook funciona de la misma manera.

  1. Abre smee.io y haz clic en Start a new channel. Copia la URL bajo Webhook Proxy URL.

  2. Si aún no tienes el cliente smee, instálalo:

    npm install --global smee-client
    
  3. Reenvía el canal a tu servidor. Reemplaza WEBHOOK_PROXY_URL con tu URL de proxy de webhook:

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

    La salida se ve así, donde WEBHOOK_PROXY_URL es tu URL de proxy de webhook:

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

    Mantenlo en ejecución mientras pruebas. Para detener el reenvío, presiona Ctrl+C. Tu servidor recibe las entregas en el puerto 3000 en la ruta /webhook, así que configura tu código para escuchar ahí.

  4. En la página de Webhooks, crea un webhook con la URL de proxy de webhook como su Payload URL.


Payload de entrega

Meshy envía una entrega mientras una tarea está IN_PROGRESS, y otra cuando la tarea alcanza un estado final. Una tarea puede alcanzar su estado final sin una entrega IN_PROGRESS.

Cada entrega es un POST a tu URL de payload con estos encabezados:

EncabezadoValor
X-MESHY-API-WEBHOOK-SECRET-KEYEl secreto del webhook
X-MESHY-API-WEBHOOK-USER-IDEl ID del usuario de Meshy propietario del webhook
Meshy-Webhook-Versionv1, el formato del cuerpo
Content-Typeapplication/json
User-AgentMeshyAPIWebhook/1.0.0

El cuerpo JSON es el objeto de la tarea. Es el mismo objeto que devuelve el endpoint GET de la tarea, excepto progress. Una entrega envía progress como uno de estos valores:

  • 50 mientras la tarea está IN_PROGRESS
  • 100 cuando la tarea se completa con éxito
  • 0 cuando la tarea falla o se cancela

Para conocer los campos de cada objeto de tarea, con un ejemplo, consulta las siguientes secciones: