Tutorial
Tutorial de la API minimax-music-1.5: curl y Python Requests
En esta página
Requisitos de solicitud de minimax-music-1.5
Antes de escribir la primera línea de código, conviene tener claro qué incluye realmente una llamada de generación musical. A diferencia de la compleción de texto, una solicitud de música tiene dos entradas creativas que cumplen funciones distintas, además de varios controles que moldean la salida.
Visto desde lo alto, una solicitud a minimax-music-1.5 contiene:
- Descripción de estilo o prompt — la dirección musical: género, estado de ánimo, instrumentación, sensación de tempo, características de producción.
- Letra — el texto que realmente se canta cuando la pista lleva voz. Para solicitudes puramente instrumentales, déjalo vacío u omítelo.
- Control de estructura — por ejemplo, la duración objetivo de la pista generada, que limita la extensión de la composición del modelo.
- Identificador del modelo —
minimax-music-1.5— indica a la pasarela que enrute la tarea al backend correcto.
Modelo mental que conviene retener: la entrada de estilo le dice al modelo cómo debe sonar, y la entrada de letra le dice qué se canta. No son intercambiables. Si metes una descripción de género en el campo de letra, obtendrás una salida caótica; si dejas la letra vacía pero pides una pista con voz, el modelo tendrá que inventarla. Decide en cuál de los dos modos estás antes de empezar.
Hay dos cosas más que interiorizar antes de escribir código:
- La generación musical no es instantánea. Producir una pista terminada requiere tiempo real de cómputo, por lo que la API es asíncrona por diseño. Envías una tarea y luego recuperas el resultado. Cualquier tutorial que muestre una única llamada bloqueante te está ocultando el bucle de sondeo.
- La salida se entrega por referencia. Recibes una URL del audio generado, no los bytes en bruto en línea. Debes descargarlo o transmitirlo por separado.
Una vez que puedas explicar estas tres cosas —la diferencia entre estilo y letra, el ciclo de vida asíncrono y la salida basada en URL—, el cuerpo real de la solicitud será fácil de leer.
Configuración inicial en HiAPI
Antes de la primera llamada necesitas tres cosas: una clave de API, la dirección base del endpoint y el hábito de no codificar la clave directamente.
Clave de API
Crea la clave en la consola de tu cuenta de HiAPI. Trátala como una contraseña: autentica cada solicitud y está vinculada al uso de tu cuenta. Nunca la confirmes en el repositorio, nunca la pegues en un gist público y nunca la empaquetes en un bundle de móvil o navegador.
Dirección base del endpoint
Todas las llamadas van a la pasarela de HiAPI, que expone minimax-music-1.5 tras una única interfaz unificada. No necesitas credenciales ni SDK separados por modelo: el nombre del modelo en el cuerpo de la solicitud selecciona el backend. Consulta la documentación de referencia de la API para obtener la URL base exacta y la ruta de solicitud actual.
Mantén la clave fuera del código fuente
El patrón que funciona desde un script temporal hasta producción son las variables de entorno:
export HIAPI_API_KEY="your-key-here"
Luego léela en tiempo de ejecución. En Python es os.environ["HIAPI_API_KEY"]; en el shell es $HIAPI_API_KEY. Si usas un archivo .env local, añádelo a .gitignore antes del primer commit, no después. Para servicios desplegados, inyecta la clave mediante el gestor de secretos de la plataforma, no la incluyas en la imagen.
Haz una comprobación rápida antes de construir nada: confirma que el proceso que vas a ejecutar puede ver la clave (ejecuta echo $HIAPI_API_KEY en el mismo shell). La mayoría de los informes de «fallo de autenticación» se remontan a haber exportado la clave en una terminal y haber ejecutado el script en otra.
Primera solicitud funcional con curl
Empieza con curl. Elimina todas las capas de abstracción y te muestra exactamente qué viaja por la red. La siguiente solicitud genera una pista corta con voz; ajusta los valores de los campos según tu propia intención.
curl -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-music-1.5",
"prompt": "folk indie cálido, guitarra acústica fingerstyle, batería cepillada suave, voz íntima de campo cercano",
"lyrics": "[verse]\nLa luz de la mañana cae en el suelo de la cocina\n[chorus]\nSeguimos aquí, seguimos aquí",
"duration": 30
}'
Línea por línea:
-X POST— la generación es una operación de creación, no de lectura.Authorization: Bearer $HIAPI_API_KEY— la clave de la sección anterior, expandida por el shell, de modo que no aparece en tu historial siempre que referencies la variable.Content-Type: application/json— la pasarela espera JSON; omitir esta cabecera es una causa común de respuestas 4xx confusas.model— fija la solicitud a minimax-music-1.5.prompt— la descripción de estilo. Sé específico sobre la instrumentación y el estado de ánimo, no solo un adjetivo.lyrics— el texto cantado, con etiquetas de sección ligeras como[verse]y[chorus]para sugerir la estructura. El escape\nes el salto de línea JSON.duration— limita la duración de la pista generada en segundos.
Lo que vuelve es una referencia de tarea, no audio. Captúrala:
curl -s -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | tee job.json
Leer el cuerpo de la solicitud desde un archivo con -d @payload.json mantiene limpio el historial del shell y facilita la transición a Python: ese archivo es el cuerpo de la solicitud. Inspecciona la respuesta y anota el identificador de tarea o job y cualquier campo de estado; necesitarás ese identificador para recuperar el resultado.
Portar la solicitud a Python
La versión en Python debería sentirse como una transcripción de la llamada curl, no como una reescritura. Usa requests, lee la clave de las variables de entorno y mantén el cuerpo de la solicitud como un diccionario para que sea legible.
import os
import json
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "minimax-music-1.5",
"prompt": "folk indie cálido, guitarra acústica fingerstyle, batería cepillada suave, voz íntima de campo cercano",
"lyrics": "[verse]\nLa luz de la mañana cae en el suelo de la cocina\n[chorus]\nSeguimos aquí, seguimos aquí",
"duration": 30,
}
response = requests.post(
f"{BASE_URL}/minimax-music-1.5",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
data=json.dumps(payload),
timeout=60,
)
response.raise_for_status()
job = response.json()
print(json.dumps(job, indent=2))
Algunas notas de portabilidad para evitar sorpresas:
- Usa
json.dumpscondata=, o usajson=payload. Ambos funcionan;json=payloadhace querequestsestablezca el tipo de contenido por ti. Si pasas un diccionario directamente adata=sin serializarlo, el servidor recibirá un cuerpo codificado como formulario y lo rechazará. - Establece siempre
timeout. Sin él, una conexión estancada hará que tu proceso se cuelgue indefinidamente. Ten en cuenta que este timeout cubre el envío, no la generación; eso es lo que aborda la siguiente sección. - Llama a
raise_for_status()antes de parsear. Convierte un 4xx o 5xx en una excepción clara en lugar de un misteriosoKeyErrorcuando accedes a un campo inexistente. - Conserva el objeto de respuesta. Al depurar, imprimir
response.status_codeyresponse.textte dice mucho más que el error ya parseado.
El resultado de este script es la misma referencia de tarea que produce curl. Todo lo que ocurre después del envío —sondeo, reintentos, descarga— es idéntico en cualquier lenguaje, y por eso merece su propia sección.
Gestionar el ciclo de vida de tareas asíncronas
El error más común con la generación musical es tratarla como una compleción de chat: enviar, esperar, leer la pista. La llamada de envío vuelve rápido, pero el audio aún no existe. Tu código debe cerrar el ciclo.
Los tres estados
Cada tarea pasa por una pequeña máquina de estados:
- Enviada (Submitted) — tienes el identificador de tarea y el trabajo está en cola o ejecutándose.
- Finalizada (Finished) — el audio está listo y la respuesta incluye una URL que apunta a él.
- Fallida (Failed) — la generación se abortó; la respuesta explica por qué.
Tu bucle de sondeo debe distinguir los tres estados. Un estado submitted significa seguir esperando, no reintentar.
Sondea, no martilles
Un bucle ingenuo que lanza comprobaciones de estado tan rápido como la CPU se lo permita agota los límites de velocidad y no te dice nada nuevo: renderizar una pista tarda decenas de segundos, así que cientos de comprobaciones por minuto son puro desperdicio. Añade retroceso exponencial:
import time
def wait_for_job(job_id, base_url, api_key, interval=2.0, max_wait=300):
deadline = time.time() + max_wait
while time.time() < deadline:
r = requests.get(
f"{base_url}/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "finished":
return data
if status == "failed":
raise RuntimeError(f"job failed: {data}")
time.sleep(interval)
raise TimeoutError(f"job {job_id} not finished after {max_wait}s")
Consulta la documentación de referencia de la API para obtener la ruta de sondeo y las cadenas de estado exactas; considera los nombres anteriores como ilustrativos y alinéalos con los valores de la documentación.
Reintenta el objeto correcto
Los reintentos pertenecen a dos niveles distintos, y mezclarlos provoca trabajo duplicado. Un reintento de transporte —la llamada HTTP en sí falla por un 5xx o un reinicio de conexión— puede repetirse sin riesgo para las solicitudes de sondeo. Un reintento de generación es un nuevo envío que cuesta otro renderizado, así que solo hazlo cuando la tarea informe explícitamente de un fallo, y limita el número de intentos. Nunca reintentes el envío solo porque el sondeo va lento.
Por último, persiste el identificador de tarea en el momento en que lo recibes. Si tu proceso se cae entre el envío y la finalización, ese identificador es la única forma de recuperar una pista terminada sin pagar otra generación.
Ajustar las entradas de letra, estilo y duración
Obtener una pista usable de minimax-music-1.5 depende principalmente de escribir con intención esos dos campos de texto. Unos pocos hábitos determinan si la salida es genérica o algo que realmente publicarías.
Escribe el prompt de estilo como un briefing de productor
Una sola palabra de género le da al modelo demasiada libertad. Apila dimensiones concretas:
- Género y época — «trip hop de finales de los 90» supera a «electrónica».
- Instrumentación — nombra el instrumento principal y la sección rítmica.
- Estado de ánimo y energía — «melancólico pero con impulso» crea una tensión que un solo adjetivo no expresa.
- Características de producción — «lo-fi, saturación de cinta, estéreo amplio» guía la mezcla.
Mantenlo en una o dos frases. Los prompts largos en forma de párrafo tienden a diluir en lugar de refinar.
Estructura la letra con etiquetas
Marcadores de sección ligeros —[verse], [chorus], [bridge]— le dan al modelo un mapa de ruta y suelen producir una estructura de canción más clara que un bloque de texto sin marcar. Mantén cada línea lo bastante corta para cantarse; una línea de doce palabras rara vez encaja en una melodía. Para pistas instrumentales, omite lyrics por completo en lugar de enviar una cadena vacía con texto de estilo dentro.
Haz que la duración coincida con el material
La duración limita la composición. Una duración corta con una letra completa de verso-estribillo-verso obliga a comprimir, y el resultado suena apresurado; una duración larga con dos líneas de letra invita a la repetición. Decide primero la forma de la canción y luego establece una duración que encaje con ella. Si necesitas una pieza más larga, amplía la letra en lugar de alargar el tiempo y esperar que funcione.
Itera con cambios pequeños
Cuando una pista está cerca pero no es la correcta, cambia una sola entrada a la vez: la instrumentación en el prompt, o la palabra de tempo, o esa línea de letra que no funciona. Cambiar todo a la vez te impide saber qué campo produjo la mejora. Guarda tu mejor cuerpo de solicitud en un archivo y ramifica desde él.
Solucionar errores comunes
La mayoría de los fallos caen en unas pocas categorías reconocibles. Identifica el síntoma, aplica la solución y sigue adelante.
Fallos de autenticación
Síntoma: 401 o 403, con un mensaje relacionado con credenciales.
- Confirma que la cabecera es
Authorization: Bearer <key>; tanto la palabraBearercomo el espacio son obligatorios. - Verifica que la variable de entorno esté realmente definida en el proceso que hace la solicitud. Una clave exportada en un shell no llega a una tarea cron ni a un contenedor Docker.
- Comprueba si hay espacios en blanco o saltos de línea sobrantes copiados junto con la clave.
Cuerpo de solicitud mal formado
Síntoma: 400 con un mensaje de validación.
- Envía
Content-Type: application/json. La falta de esta cabecera hace que el servidor malinterprete un cuerpo de solicitud perfectamente correcto. - Si usas
requests, pasajson=payloadodata=json.dumps(payload). Pasar el diccionario en bruto adata=lo codifica como formulario. - Valida los nombres y tipos de campo contra la documentación de referencia de la API:
modeldebe ser exactamenteminimax-music-1.5,durationes un entero, y los saltos de línea de la letra deben escaparse correctamente como\nen JSON. - En caso de duda, usa
curl -d @payload.jsonpara aislar si el cuerpo de la solicitud es válido antes de involucrar a Python.
Timeouts y errores de conexión
Síntoma: la solicitud se cuelga o lanza un error de conexión.
- Establece un
timeoutexplícito en cada llamada. El timeout de envío debe ser lo bastante amplio para cubrir la latencia de la cola, pero no es el tiempo de renderizado. - No iguales tu timeout de sondeo al
max_waitglobal; una comprobación de estado lenta no debería abortar una tarea que sigue en marcha. - Si el envío se agota repetidamente mientras el sondeo funciona, puede que tu cuerpo de solicitud sea demasiado grande; reduce la letra.
Errores de sondeo
Síntoma: sigues sondeando y nunca ves finished, o estás sondeando el recurso equivocado.
- Confirma que usas el identificador de tarea de la respuesta de envío, no el ID de solicitud ni una cabecera de correlación.
- Trata
submitted/runningcomo «sigue esperando», no como «reintenta el envío». Reenviar crea una segunda pista. - Añade retroceso. El sondeo agresivo atrae límites de velocidad, que parecen un fallo pero son obra tuya.
- Si la tarea informa
failed, lee el mensaje antes de reenviar: una etiqueta de letra inválida o una duración fuera de rango fallará de la misma forma cada vez.
Cuando te quedes atascado, vuelve a la llamada curl original añadiendo -v para ver la línea de estado y las cabeceras reales. Ese paso resuelve la mayoría de las ambigüedades más rápido que cualquier cantidad de depuración en Python.
Artículos relacionados
Ver todos los artículos →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio