Webhooks vs. sondeo de 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 más) se ejecutan de forma asíncrona: envías una tarea y luego necesitas saber cuándo ha terminado antes de obtener el resultado. Este artículo explica el ciclo de vida de las tareas y las dos formas admitidas de saber cuándo una tarea ha finalizado: el sondeo (polling) 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, devueltos en el campo status del objeto de la tarea:

• PENDING: la tarea está 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 se completa el trabajo.

• SUCCEEDED: la tarea finalizó correctamente y progress es 100. Las URL de los resultados (archivos del 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 fue cancelada antes de completarse.

La regla más importante al integrarte con la API es: nunca intentes obtener ni usar las URL de los resultados hasta que el status de la tarea sea SUCCEEDED. Leer los resultados mientras la tarea todavía está en PENDING o IN_PROGRESS es la causa más frecuente de los informes de «errores al recuperar el modelo».

El sondeo significa llamar repetidamente al endpoint de «obtener tarea» para el ID de tu tarea hasta que alcance un estado terminal (SUCCEEDED, FAILED o CANCELED). Un bucle de sondeo simple se ve así:

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

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

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

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

• Añade un límite razonable de tiempo de espera o número máximo de intentos en tu cliente para que una tarea atascada no haga sondeos indefinidamente.

El sondeo es simple y funciona bien para scripts, trabajos por lotes e integraciones de bajo volumen. Para integraciones de alto volumen o sensibles a la latencia, un webhook suele ser una mejor opción.

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

• Configura una URL de webhook (callback) que Meshy pueda alcanzar; esto generalmente se establece a 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 a través de HTTPS y responda rápidamente (devuelve un estado 2xx de inmediato y luego procesa el payload de forma asíncrona).

• Cuando la tarea alcance un estado terminal, Meshy enviará un payload a tu endpoint con el id de la tarea y su status final.

• Al recibirlo, consulta los detalles completos de la tarea por id a través de la API en lugar de confiar solo en el cuerpo del webhook, para asegurarte de tener el resultado autorizado 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 respaldo de sondeo periódico 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, es decir, seguro para 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 remitente, duplicación en la red, etc.).

• Un bucle de sondeo y un controlador de webhook 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, comprueba si ya has almacenado o descargado los resultados de ese id antes de hacerlo de nuevo, y convierte «marcar como procesada» en 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 (URL del modelo, texturas, miniaturas) está completo y es seguro de usar. En concreto, en tu código:

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

• No confíes solo en progress; comprueba siempre también status, ya que el progreso puede mostrar brevemente valores altos antes de que la tarea esté completamente finalizada.

• Descarga los archivos de resultados con prontitud una vez que el estado sea SUCCEEDED; los recursos generados solo se conservan en los servidores de Meshy durante un tiempo limitado, después del cual las URL dejarán de funcionar.

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

• Obtener los resultados demasiado pronto. Llamar a la URL del 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 los resultados dejan de funcionar una vez transcurrida la ventana de retención de 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 volver a enviarla.

• Problemas de red o de tiempo de espera entre tu servidor y Meshy que se malinterpretan como un problema de generación.

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

• La API de Meshy actualmente no admite reintentar una tarea existente en su lugar; para intentarlo de nuevo, envía una nueva solicitud de generación, que consumirá créditos con normalidad.

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

• Para el sondeo en sí, reintenta la llamada de «obtener tarea» ante errores de red transitorios, pero no trates un único sondeo fallido como un fallo de generación; confía únicamente en el campo status una vez que recibas una respuesta exitosa.

• Si necesitas una función de reintento integrada para las generaciones, contacta con el equipo de ventas de Meshy para conocer las opciones de planes empresariales.

Esto casi siempre sucede porque el código intenta leer el resultado antes de que la tarea haya terminado. Confirma siempre que status sea SUCCEEDED (y que progress sea 100) antes de recuperar las URL del modelo.

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

Manéjalo de forma idempotente: comprueba el id de la tarea con lo que ya has procesado y omite el reprocesamiento si ya se ha gestionado.

Recurre al sondeo de la tarea directamente por su id. También confirma que tu endpoint sea accesible públicamente a través de 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, que consume créditos con normalidad. Contacta con ventas sobre las opciones empresariales si necesitas compatibilidad con reintentos integrados.

Los archivos de resultados solo se conservan en los servidores de Meshy durante un tiempo limitado después de que una tarea se completa, así que descarga los resultados en tu propio almacenamiento tan pronto como la tarea se complete con éxito, en lugar de esperar.

• ¿Por qué encuentro errores constantemente al recuperar los modelos del resultado de generación usando la API?