Como chamar a API minimax-music-3: tutorial de geração de música a partir de texto com curl e Python

Modos comuns de falha e técnicas de depuração

A geração assíncrona falha de algumas formas previsíveis. Quando algo der errado, verifique o seguinte.

A tarefa nunca aparece — o envio retorna 4xx

Um 400 no envio quase sempre significa que o payload da requisição está malformado: model ausente ou com erro de digitação, prompt vazio, ou duration enviado como string em vez de número. Um 401 indica chave ausente, expirada ou cabeçalho malformado — confira primeiro a própria string do cabeçalho. Imprima o corpo da resposta, não apenas o código de status; o corpo de erro da API normalmente aponta o campo problemático.

O polling nunca termina

Se o seu loop nunca sai, ou a tarefa travou, ou sua condição de estado terminal está errada. Registre cada valor de status que observar. Se um status desconhecido aparecer repetidamente, sua condição de conclusão está restrita demais. Se nada mudar por muitos minutos além do tempo esperado, trate como falha e registre o objeto da tarefa no log — e certifique-se de definir um prazo limite para não bloquear o worker indefinidamente.

Polling prematuro

Consultar o status antes de a tarefa ser registrada ou antes da primeira transição de estado pode retornar 404 ou o estado inicial "queued". Isso é normal. Para um 404 retornado pela consulta de status, trate com algumas tentativas com backoff em vez de travar imediatamente — um not-found temporário logo após o envio é uma condição de corrida, não um erro. Desista apenas após várias falhas consecutivas.

Timeouts e estagnação de rede

Se as requisições falharem por timeout intermitentemente, confirme que você define explicitamente um timeout em cada chamada, em vez de depender do padrão da biblioteca. Verifique também se você não está consultando com frequência excessiva — requisições densas de status podem acionar limitação de taxa, normalmente manifestada como timeouts ou 429, e não como um erro claro.

URL do resultado expirada

Uma falha comum em produção: a tarefa teve sucesso, você salvou a URL e, dias depois, o download retorna 403. As URLs de resultado têm validade curta. Baixe imediatamente no mesmo worker que observou o sucesso. Se o download falhar, tente novamente algumas vezes e então reenvie ou consulte novamente o status da tarefa — não marque a tarefa como concluída antes de os dados estarem gravados com segurança no seu armazenamento.

Repetições geram tarefas duplicadas

Se a chamada de envio der timeout, você pode não saber se a tarefa foi aceita. Repetir pode gerar duas músicas e duas cobranças. Quando a segurança de repetição for importante, registre um ID de requisição do cliente para o envio e verifique as tarefas recentes para conferência antes de reenviar às cegas. Melhor ainda, projete o sistema para que o envio ocorra apenas uma vez, a partir de uma fila persistente, e o polling ocorra a jusante.

Um padrão que vale adotar por fim: no momento do envio, grave o ID da tarefa e o status no seu próprio banco de dados. Assim, seu endpoint de status, a barra de progresso da UI e a depuração leem dos seus registros — em vez de fazer polling ad hoc na thread da requisição. Essa é a diferença entre uma demonstração e um recurso que resiste ao uso real.