Webhooks vs. sondeo en la API de Meshy: cuándo están listos los resultados

Las tareas de generación de la API de Meshy (Text to 3D, Image to 3D, Rigging y demás) se ejecutan de forma asíncrona: envías una tarea y luego debes averiguar cuándo ha terminado antes de obtener el resultado. En este artículo se explica el ciclo de vida de la tarea y las dos formas admitidas de saber cuándo ha finalizado una tarea: el sondeo y los webhooks, además de cómo evitar el problema más común de «errores al recuperar el modelo».

Cada tarea de generación pasa por un pequeño conjunto de estados, que se devuelven en el campo status del objeto de tarea:

• PENDING — la tarea se ha puesto en cola, pero el procesamiento aún no ha comenzado.

• IN_PROGRESS — la tarea se está procesando activamente. El campo progress (0-100) aumenta a medida que avanza el trabajo.

• SUCCEEDED — la tarea finalizó correctamente y progress es 100. Las URLs de los resultados (archivos de modelo, texturas, vistas previas) ya están disponibles en la respuesta.

• FAILED — la tarea no pudo completarse. Los créditos de las tareas fallidas se reembolsan automáticamente.

• CANCELED — la tarea se canceló antes de completarse.

La regla más importante al integrar la API: nunca intentes obtener ni usar las URLs de resultados hasta que el status de la tarea sea SUCCEEDED. Leer los resultados mientras una tarea sigue en PENDING o IN_PROGRESS es la causa más común de los informes de "errores al recuperar el modelo".

El sondeo consiste en llamar repetidamente al endpoint «obtener tarea» para tu ID de tarea hasta que alcance un estado terminal (SUCCEEDED, FAILED o CANCELED). Un bucle de sondeo sencillo tiene este aspecto:

• Envía la solicitud de generación y guarda el id de tarea devuelto.

• Llama al endpoint «recuperar tarea» correspondiente (por ejemplo, el endpoint de tarea por ID de Text to 3D o Image to 3D) a intervalos regulares; unos pocos segundos es lo habitual.

• Comprueba el campo status en cada respuesta. Sigue sondeando mientras sea PENDING o IN_PROGRESS.

• Deja de sondear en cuanto status sea SUCCEEDED (lee las URL del resultado), FAILED o CANCELED.

• Añade en tu cliente un límite razonable de tiempo de espera o de intentos máximos para que una tarea bloqueada no se sondee indefinidamente.

El sondeo es sencillo y funciona bien para scripts, trabajos por lotes e integraciones de bajo volumen. Para integraciones de gran volumen o sensibles a la latencia, un webhook suele encajar mejor.

En lugar de preguntar repetidamente "¿ya está listo?", puedes pedirle a Meshy que notifique a tu servidor en el momento en que finalice una tarea. Para usar webhooks:

• Configura una URL de webhook (callback) a la que Meshy pueda acceder; esto normalmente se establece en el nivel de configuración de la cuenta/API o se pasa como parámetro en la solicitud de generación, según el endpoint.

• Asegúrate de que tu endpoint sea accesible públicamente mediante HTTPS y responda con rapidez (devuelve un estado 2xx de inmediato y luego procesa el payload de forma asíncrona).

• Cuando la tarea alcanza un estado terminal, Meshy envía un payload a tu endpoint que contiene el id de la tarea y su status final.

• Al recibirlo, consulta los detalles completos de la tarea por id mediante la API en lugar de confiar únicamente en el cuerpo del webhook, para asegurarte de tener el resultado autoritativo y actualizado.

Los webhooks reducen las llamadas innecesarias a la API y te ofrecen una notificación casi instantánea, pero aun así deberías mantener un sondeo periódico como respaldo para las tareas en las que la entrega de un webhook pueda perderse o retrasarse (por ejemplo, debido a un problema de red transitorio de tu lado).

Ya sea que uses sondeo o webhooks, tu código de manejo de resultados debe ser idempotente: seguro de ejecutarse más de una vez para la misma tarea sin efectos secundarios. Esto es importante porque:

• Un webhook puede entregarse más de una vez para la misma tarea (reintentos del lado del emisor, duplicación de red, etc.).

• Un bucle de sondeo y un controlador de webhooks podrían intentar procesar la misma tarea completada si ambos están en ejecución.

Para mantener la idempotencia, basa tu lógica de procesamiento en el id de la tarea; por ejemplo, verifica si ya has almacenado o descargado los resultados de ese id antes de volver a hacerlo, y haz que «marcar como procesado» sea un único paso atómico en tu propia base de datos.

Una respuesta con "status": "SUCCEEDED" y "progress": 100 es la única señal que garantiza que el payload del resultado (URLs del modelo, texturas, miniaturas) está completo y se puede usar de forma segura. En concreto, en tu código:

• Verifica status === "SUCCEEDED" antes de leer cualquier dato de los campos result o de la URL del modelo.

• No te bases solo en progress: comprueba siempre también status, ya que el progreso puede mostrar valores altos de forma momentánea antes de que la tarea esté totalmente finalizada.

• Descarga los archivos de resultado en cuanto aparezca SUCCEEDED: los recursos generados solo se conservan en los servidores de Meshy durante un tiempo limitado, tras el cual las URL dejarán de resolverse.

La mayoría de los informes de «no puedo recuperar mi modelo» se remontan a una de estas causas:

• Consultar demasiado pronto. Llamar a la URL de resultado, o leer los campos del modelo, antes de que status sea SUCCEEDED. Esta es, con diferencia, la causa más frecuente.

• Recursos caducados. Esperar demasiado después de SUCCEEDED para descargar: las URL de resultado dejan de funcionar una vez transcurrida la ventana de retención para ese tipo de tarea.

• Usar un ID de tarea obsoleto o incorrecto, por ejemplo, reutilizar un ID de una solicitud anterior no relacionada.

• Tratar FAILED como un estado transitorio y seguir sondeando una tarea que ya ha fallado en lugar de reenviarla.

• Problemas de red/tiempo de espera entre tu servidor y Meshy que se interpretan erróneamente como un problema de generación.

Si una generación no cumple tus expectativas, o si una solicitud falla por completo, ten en cuenta lo siguiente:

• Actualmente, la API de Meshy no admite reintentar una tarea existente en el mismo lugar; para volver a intentarlo, envía una nueva solicitud de generación, lo que consumirá créditos con normalidad.

• Para fallos de red transitorios al llamar a la API (tiempos de espera agotados, respuestas 5xx), es razonable aplicar un breve retroceso exponencial antes de reenviar la solicitud.

• Para el propio sondeo, reintenta la llamada de «obtener tarea» ante errores de red transitorios, pero no consideres un único sondeo fallido como un fallo de generación; solo confía en el campo status cuando obtengas una respuesta correcta.

• Si necesitas funcionalidad de reintento integrada para las generaciones, ponte en contacto con el equipo de ventas de Meshy para conocer las opciones de los planes enterprise.

Esto casi siempre ocurre porque el código intenta leer el resultado antes de que la tarea haya finalizado. Confirma siempre que status sea SUCCEEDED (y que progress sea 100) antes de recuperar las URL de los modelos.

El sondeo es más sencillo de configurar y es adecuado para scripts de bajo volumen o puntuales. Los webhooks son mejores para integraciones de producción con muchas tareas simultáneas, ya que evitan solicitudes repetidas innecesarias y te notifican de inmediato cuando una tarea finaliza.

Gestiónalo de forma idempotente: comprueba el id de la tarea con lo que ya has procesado y omite el reprocesamiento si ya se ha gestionado.

Usa el sondeo de la tarea por id directamente como alternativa. También confirma que tu endpoint sea accesible públicamente mediante HTTPS y devuelva una respuesta 2xx rápida, ya que los endpoints lentos o inaccesibles pueden causar problemas de entrega.

Actualmente no: tendrás que enviar una nueva solicitud de generación, lo que consume créditos con normalidad. Contacta con ventas para consultar las opciones empresariales si necesitas compatibilidad con reintentos integrada.

Los archivos de resultado solo se conservan en los servidores de Meshy durante un tiempo limitado después de que finalice una tarea, así que descarga los resultados en tu propio almacenamiento en cuanto la tarea se complete, en lugar de esperar.