Come chiamare l'API minimax-music-3: tutorial curl e Python per generare musica da testo

Modalità di errore comuni e tecniche di debug

La generazione asincrona fallisce in alcuni modi prevedibili. Quando qualcosa va storto, controlla quanto segue.

L'attività non compare mai — l'invio restituisce 4xx

Un 400 al momento dell'invio significa quasi sempre che il payload della richiesta è formattato male: model mancante o scritto male, prompt vuoto, oppure duration inviato come stringa invece che come numero. 401 indica una chiave mancante, scaduta o un formato errato dell'header — verifica prima la stringa dell'header stessa. Stampa il corpo della risposta, non solo il codice di stato; il corpo di errore dell'API di solito indica il campo problematico.

Il polling resta appeso per sempre

Se il tuo ciclo non termina mai, o l'attività è bloccata o la tua condizione di stato finale è sbagliata. Registra ogni valore di stato che osservi. Se vedi ripetersi uno stato che non conosci, la tua condizione di completamento è troppo restrittiva. Se non cambia nulla per molti minuti oltre la durata prevista, trattalo come un fallimento e scrivi l'oggetto attività nel log — e assicurati di impostare una scadenza per evitare di bloccare il worker a tempo indeterminato.

Polling troppo precoce

Eseguire il polling prima che l'attività sia registrata o che avvenga la prima transizione di stato può restituire 404 o lo stato iniziale "queued". È normale. Per un 404 restituito dall'interrogazione dello stato, gestiscilo con alcuni tentativi con backoff invece di andare in crash — un not-found temporaneo subito dopo l'invio è una race condition, non un errore. Rinuncia solo dopo diversi fallimenti consecutivi.

Timeout e stallo di rete

Se le richieste vanno in timeout in modo intermittente, verifica di aver impostato esplicitamente un timeout su ogni chiamata, invece di affidarti ai valori predefiniti della libreria. Controlla anche di non fare polling troppo frequentemente — richieste di stato ravvicinate possono attivare il rate limiting, che di solito si manifesta come timeout o 429 anziché come un errore chiaro.

URL del risultato scaduto

Un guasto comune in produzione: l'attività riesce, salvi l'URL e qualche giorno dopo il download restituisce 403. Gli URL dei risultati hanno una validità molto breve. Scarica subito, nello stesso worker che ha osservato il successo. Se il download fallisce, riprova alcune volte, poi invia di nuovo o riottieni lo stato dell'attività — non contrassegnare l'attività come completata finché i dati non sono scritti in modo sicuro nel tuo storage.

I tentativi ripetuti causano attività duplicate

Se la chiamata di invio va in timeout, potresti non sapere se l'attività è stata accettata. Un nuovo tentativo può produrre due brani e due addebiti. Quando la sicurezza dei tentativi è importante, registra un ID richiesta lato client per la richiesta di invio e, prima di reinviare alla cieca, controlla le attività recenti per verificare. Meglio ancora, progetta il sistema in modo che l'invio avvenga una sola volta da una coda persistente e il polling avvenga a valle.

Un'ultima modalità che vale la pena adottare: al momento dell'invio, salva l'ID dell'attività e lo stato nel tuo database. Così il tuo endpoint di stato, la barra di avanzamento della UI e il debug leggono dai tuoi record — invece di fare polling estemporaneo nel thread della richiesta. È questa la differenza tra una demo e una funzionalità che regge.