API de minimax-music-3: guía de curl y Python

Generar una pista con minimax-music-3 en hiapi requiere solo una llamada POST /v1/tasks más sondeo; exactamente el mismo patrón de tareas asíncronas que usan todos los modelos de la plataforma. Esta guía documenta las solicitudes y respuestas reales (creación de la tarea, sondeo y la URL final del audio), por lo que el código a continuación se puede copiar y ejecutar directamente, no es solo ilustrativo.

Qué necesitas preparar

1. Una clave de API de hiapi: créala en la consola. Se envía como token Bearer en cada solicitud.
2. Eso es todo. A diferencia de los modelos de imagen a vídeo o imagen a imagen, minimax-music-3 no acepta ningún archivo ni entrada de URL: genera únicamente a partir de texto.

Solicitud mínima funcional (curl)

Crear la tarea:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-3",
    "input": {
      "prompt": "chill lofi hip hop beat, mellow piano, soft drums",
      "lyrics": "[Instrumental]"
    }
  }'

Respuesta:

{"code":200,"data":{"taskId":"tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55"},"message":"success"}

Sondea la tarea hasta que se complete:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55 \
  -H "Authorization: Bearer sk-<your-key>"

Mientras la tarea se ejecuta, status pasa por handling → archiving y finalmente llega a success (o failed). En las pruebas, una pista tardó aproximadamente dos minutos y medio desde el envío hasta success. La respuesta al completarse es la siguiente:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55",
    "status": "success",
    "model": "minimax-music-3",
    "created": 1787018905,
    "completed": 1787019051,
    "storage": "temp",
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M09A11R6WEC2JDQ8RK6E7N55-0.wav",
        "artifactId": "78585",
        "expireAt": 1787623851
      }
    ]
  },
  "message": "success"
}

output[0].url es el archivo WAV. Fíjate en expireAt: antes de construir cualquier funcionalidad que dependa de que esa URL siga siendo válida a largo plazo, lee la nota sobre almacenamiento que aparece más abajo.

El mismo flujo en Python

import time
import requests

API_KEY = "sk-<your-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_track(prompt: str, lyrics: str = "[Instrumental]") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "minimax-music-3", "input": {"prompt": prompt, "lyrics": lyrics}},
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_track(task_id: str, timeout_s: int = 300, interval_s: int = 6) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_track("upbeat synthwave, driving bassline, retro 80s")
    audio_url = wait_for_track(task_id)
    audio = requests.get(audio_url, timeout=60).content
    with open("track.wav", "wb") as f:
        f.write(audio)
    print(f"saved track.wav from task {task_id}")

Parámetros que minimax-music-3 valida realmente

El esquema de entrada es estricto: si envías un campo no listado, la API rechaza toda la solicitud antes de que entre en la cola:

• prompt (cadena, obligatorio): estilo, estado de ánimo, instrumentación. Esto determina en la práctica la forma de la pista.
• lyrics (cadena, obligatorio): siempre obligatorio, incluso para pistas puramente instrumentales. Pasa "[Instrumental]" como marcador de posición; para pistas con voz, usa etiquetas de sección como [Verse] / [Chorus].
• callback (objeto, opcional): {"url": "...", "when": "final"}. El único valor admitido para when es "final"; cualquier otro valor devuelve un 400 con el mensaje de error invalid callback.when: only 'final' is supported.

Si envías cualquier cosa fuera de estas tres claves de nivel superior, como sample_rate, duration o una errata, obtendrás:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'sample_rate' not allowed"}

Consideraciones para producción

• Dos formas distintas de error. Los errores de validación (campos faltantes, valores de enumeración incorrectos, claves desconocidas) devuelven en el nivel superior {"code":400,"error_code":"INVALID_REQUEST","message":"..."}. Los errores de autenticación/permisos devuelven {"error":{"code":"permission_denied","message":"...","request_id":"..."}}, un objeto error anidado, con HTTP 401. Comprueba ambas formas en tu manejo de errores; el código que solo revisa resp["code"] pasará por alto los casos de 401.
• permission_denied indica un problema con la clave, no con la solicitud. Si prompt/lyrics están presentes y tienen el tipo correcto, pero aun así recibes un 401 permission_denied, significa que esa clave de API no tiene habilitado este modelo: revísalo en la consola en lugar de releer tu JSON una y otra vez.
• El almacenamiento de los archivos de salida es temporal. storage: "temp" y una marca de tiempo Unix expireAt en cada salida; en el ejemplo capturado, aproximadamente 7 días después de la creación. En cuanto la tarea se complete, descarga el archivo o súbelo a tu propio almacenamiento de inmediato; no guardes las URL de temp.hiapi.ai como enlaces permanentes.
• Para cualquier tarea por lotes, usa callbacks. Sondear una pista está bien; sondear cincuenta son cincuenta idas y vueltas repetidas. Configura callback.url y when: "final" para que hiapi te envíe el resultado de una sola vez cuando la tarea se complete realmente.
• Reintenta antes de obtener el taskId, no después. Reintentar la POST /v1/tasks inicial ante un error de red o un 5xx es seguro: en ese momento aún no se ha creado nada. Una vez que tienes el taskId, reenviar el mismo prompt crea otra pista no relacionada; en ese punto, sondea o espera el callback.

Contenido relacionado

• Página del modelo minimax-music-3: precios actuales y zona de prueba en línea.
• Precios de hiapi: tarifas de todos los modelos del catálogo.
• Documentación de hiapi: referencia completa de la API más allá de este único modelo.

Preguntas frecuentes

¿Hay que proporcionar letras para una pista puramente instrumental? Sí: tanto si quieres voces como si no, lyrics es un campo obligatorio. Pasa "[Instrumental]" y el modelo generará una pista sin voz.

¿Se puede evitar por completo el sondeo? Sí, configura callback: {"url": "https://your-endpoint", "when": "final"} al crear la tarea. Cuando la tarea alcanza un estado terminal, hiapi envía por POST a tu URL la misma carga útil que devuelve GET /v1/tasks/:id. "final" es actualmente el único valor admitido para when.

¿Por qué recibo "additional properties not allowed"? El esquema de entrada de minimax-music-3 solo acepta prompt y lyrics dentro de input (además de callback en el nivel superior). Cualquier otro nombre de campo, aunque funcione en otros modelos de hiapi, se rechaza antes de que la solicitud se ejecute.

¿Por qué una clave que funciona en otros modelos devuelve 401 en este? El acceso a los modelos se concede por clave. Un 401 con error_code: "permission_denied" significa que a esa clave concreta aún no se le ha concedido permiso para minimax-music-3: habilítalo en la consola, no es un bug de tu cuerpo de solicitud.

¿Cuánto tiempo puedo esperar antes de descargar el archivo de salida? No esperes: output[0].url es un enlace temporal (en la práctica, expireAt es aproximadamente una semana después). Trátalo como una entrega de un solo uso: descarga o vuelve a subir el archivo en cuanto la tarea se complete.