Как вызвать API minimax-music-3: руководство по генерации музыки из текста с помощью curl и Python

Типичные сценарии сбоев и приёмы отладки

Асинхронная генерация может сбоить несколькими предсказуемыми способами. При возникновении проблем проверьте следующее.

Задача так и не появилась — отправка вернула 4xx

Код 400 при отправке почти всегда означает, что тело запроса сформировано неверно: model отсутствует или написан с ошибкой, prompt пуст, или duration передан строкой, а не числом. 401 означает, что ключ отсутствует, истёк или заголовок запроса сформирован неверно — сначала проверьте саму строку заголовка. Печатайте тело ответа, а не только код состояния; тело ответа с ошибкой API обычно указывает проблемное поле.

Опрос зависает навсегда

Если ваш цикл никогда не завершается, либо задача застряла, либо вы неверно определяете конечное состояние. Записывайте каждое наблюдаемое значение состояния. Если какое-то незнакомое состояние повторяется, значит условие завершения слишком узкое. Если за много минут дольше ожидаемого ничего не меняется, считайте это сбоем и выведите объект задачи в лог — и обязательно задайте крайний срок, чтобы не блокировать рабочий процесс бесконечно.

Опрос слишком рано

Опрос до регистрации завершения задачи или до первого перехода состояния может вернуть 404 или начальное состояние «queued». Это нормально. На 404 при запросе статуса следует реагировать несколькими повторными попытками с экспоненциальной задержкой, а не падать сразу — временный not-found сразу после отправки является гонкой, а не ошибкой. Сдавайтесь только после нескольких последовательных неудач.

Тайм-ауты и сбои сети

Если запросы периодически завершаются по тайм-ауту, убедитесь, что вы явно задаёте тайм-аут для каждого вызова, а не полагаетесь на значения по умолчанию библиотеки. Также проверьте, не опрашиваете ли вы слишком часто — частые запросы статуса могут вызвать ограничение скорости, которое обычно проявляется как тайм-аут или 429, а не как понятная ошибка.

URL результата истекает

Частая проблема в production: задача завершилась, вы сохранили URL, а через несколько дней скачивание возвращает 403. URL результата имеет короткий срок действия. Скачивайте сразу в том же рабочем процессе, где наблюдали успех. Если скачивание не удалось, повторите несколько раз, затем отправьте задачу заново или снова получите её статус — не помечайте задачу как завершённую, пока данные не записаны в ваше хранилище безопасно.

Повторные попытки создают дублирующиеся задачи

Если вызов отправки завершился по тайм-ауту, вы можете не знать, была ли задача принята. Повторная попытка может создать две песни и два списания. Когда безопасность повторных попыток важна, записывайте клиентский ID запроса для отправки и перед слепой повторной отправкой проверяйте последние задачи для сверки. Ещё лучше — спроектировать систему так, чтобы отправка происходила только один раз из持久 очереди, а опрос выполнялся ниже по потоку.

И последний шаблон, который стоит применять: в момент отправки сохраняйте ID задачи и статус в собственной базе данных. Тогда ваша конечная точка статуса, индикатор прогресса в UI и отладка читают из ваших записей — а не опрашивают на лету в потоке запроса. Это и есть разница между демонстрацией и функцией, прошедшей проверку временем.