Blog

Tutorial

Tutorial de la API minimax-music-1.5: curl y Python Requests

Nov 12, 2026
Imagen de portada: sobre un fondo de carbón cálido, una amplia banda de luz ámbar cruza diagonalmente una rendija, acompañada de discretos bloques geométricos oscuros; composición sobria con amplio espacio en blanco.
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:

  1. 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.
  2. 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 \n es 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.dumps con data=, o usa json=payload. Ambos funcionan; json=payload hace que requests establezca el tipo de contenido por ti. Si pasas un diccionario directamente a data= 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 misterioso KeyError cuando accedes a un campo inexistente.
  • Conserva el objeto de respuesta. Al depurar, imprimir response.status_code y response.text te 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:

  1. Enviada (Submitted) — tienes el identificador de tarea y el trabajo está en cola o ejecutándose.
  2. Finalizada (Finished) — el audio está listo y la respuesta incluye una URL que apunta a él.
  3. 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 palabra Bearer como 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, pasa json=payload o data=json.dumps(payload). Pasar el diccionario en bruto a data= lo codifica como formulario.
  • Valida los nombres y tipos de campo contra la documentación de referencia de la API: model debe ser exactamente minimax-music-1.5, duration es un entero, y los saltos de línea de la letra deben escaparse correctamente como \n en JSON.
  • En caso de duda, usa curl -d @payload.json para 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 timeout explí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_wait global; 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/running como «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 →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API