Cómo llamar a la API minimax-music-3: tutorial de curl y Python para generar música a partir de texto

Modos de fallo habituales y técnicas de depuración

La generación asíncrona falla de varias formas predecibles. Cuando algo salga mal, revisa lo siguiente.

La tarea nunca aparece: el envío devuelve 4xx

Un 400 al enviar casi siempre significa que la carga útil de la solicitud está mal formada: falta model o está mal escrito, prompt está vacío, o duration se envía como cadena en lugar de número. 401 indica que la clave falta, ha caducado o el formato de la cabecera es incorrecto; verifica primero la propia cadena de la cabecera. Imprime el cuerpo de la respuesta, no solo el código de estado; el cuerpo de error de la API suele indicar el campo problemático.

El sondeo se queda colgado para siempre

Si tu bucle nunca termina, o la tarea está atascada, o tu criterio de estado final está mal escrito. Registra cada valor de estado que observes. Si aparece repetidamente un estado desconocido, tu condición de finalización es demasiado restrictiva. Si no hay ningún cambio tras muchos minutos más de lo esperado, trátalo como un fallo y vuelca el objeto de la tarea al log; además, asegúrate de establecer una fecha límite para no bloquear el proceso de trabajo indefinidamente.

Sondeo prematuro

Sondear antes de que la tarea termine de registrarse o antes de la primera transición de estado puede devolver 404 o el estado inicial «queued». Esto es normal. Para el 404 que devuelve la consulta de estado, gestiona unos cuantos reintentos con retroceso exponencial en lugar de fallar directamente; el not-found temporal que aparece justo después del envío es una condición de carrera, no un error. Abandona solo tras varios fallos consecutivos.

Tiempos de espera y estancamiento de la red

Si las solicitudes agotan el tiempo de espera de forma intermitente, confirma que estableces un tiempo de espera explícito en cada llamada en lugar de depender del valor predeterminado de la biblioteca. Comprueba también si estás sondeando con demasiada frecuencia; las solicitudes de estado intensivas pueden activar la limitación de tasa, que suele manifestarse como tiempos de espera agotados o 429 en lugar de un error claro.

La URL del resultado caduca

Un fallo común en producción: la tarea se completa, guardas la URL y, días después, la descarga devuelve 403. Las URL de resultado tienen una validez muy corta. Descarga inmediatamente en el mismo proceso de trabajo en el que observaste el éxito. Si la descarga falla, reintenta unas cuantas veces y luego vuelve a enviar o a consultar el estado de la tarea; no marques la tarea como completada hasta que los datos estén escritos de forma segura en tu almacenamiento.

Los reintentos generan tareas duplicadas

Si la llamada de envío agota el tiempo de espera, puede que no sepas si la tarea fue aceptada. Un reintento puede producir dos canciones y dos cargos. Cuando la seguridad de los reintentos es importante, registra un ID de solicitud de cliente para la solicitud de envío y, antes de reenviar a ciegas, revisa las tareas recientes para verificarlo. Mejor aún, diseña el sistema para que el envío ocurra una sola vez desde una cola persistente y el sondeo se realice aguas abajo.

Un patrón que vale la pena adoptar por último: en el momento del envío, guarda el ID de la tarea y el estado en tu propia base de datos. Así, tu endpoint de estado, la barra de progreso de la interfaz y la depuración leen de tus registros, en lugar de sondear de forma improvisada en el hilo de la solicitud. Esa es la diferencia entre una demo y una función que resiste la prueba del tiempo.