Cómo usar lyria-3-pro a través de la API de hiapi: curl, Python y ejemplos de solicitudes ejecutables

lyria-3-pro es un modelo de generación musical disponible a través de la API de hiapi: envía un prompt de texto y obtén una pista de audio completa. Esta guía recorre el flujo de solicitud que realmente devuelve un taskId, explica el schema de entrada completo (muy breve) y los detalles de producción que necesitarás una vez que superes la prueba puntual.

Lo que necesitas

• Una API key de hiapi. Obtén una desde la consola: la key empieza por sk-.
• curl o requests de Python. No se necesita SDK; hiapi usa REST estándar.

lyria-3-pro se ejecuta sobre la API unificada de tareas asíncronas de hiapi: haces POST de una tarea, obtienes inmediatamente un taskId y luego consultas el resultado o recibes un callback cuando la pista esté lista.

Ejemplo mínimo ejecutable

1. Crear una tarea

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3-pro",
    "input": {
      "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood"
    }
  }'

Una respuesta correcta vuelve inmediatamente, antes de que la pista se haya renderizado realmente:

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

2. Consultar el resultado

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M0T17T7RERV481QJC3DRZCRS" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Espera unos segundos antes de la primera consulta y luego comprueba cada 3–5 segundos. El status pasa por estados intermedios como archiving y finalmente llega a un estado terminal:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T17T7RERV481QJC3DRZCRS",
    "model": "lyria-3-pro",
    "status": "success",
    "created": 1787580115,
    "completed": 1787580157,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T17T7RERV481QJC3DRZCRS-0.mp3",
        "expireAt": 1788184956
      }
    ]
  }
}

Descarga output[0].url lo antes posible: la capa de almacenamiento temp predeterminada caduca en unos 7 días (expireAt es una marca de tiempo Unix). En caso de fallo, status es fail y data.error contiene { code, message } en lugar de output.

3. La misma solicitud en Python

import time
import requests

API_KEY = "sk-YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "lyria-3-pro",
    "input": {
        "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood",
    },
}

create = requests.post("https://api.hiapi.ai/v1/tasks", headers=HEADERS, json=payload)
task_id = create.json()["data"]["taskId"]

while True:
    time.sleep(3)
    detail = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = detail["data"]["status"]
    if status == "success":
        print(detail["data"]["output"][0]["url"])
        break
    if status == "fail":
        raise RuntimeError(detail["data"]["error"])

Schema de entrada completo

input acepta exactamente dos campos; cualquier cosa fuera de esta lista se rechaza con 400 INVALID_REQUEST:

Campo	Tipo	Obligatorio	Descripción
prompt	string	Sí	Describe el género, la instrumentación, el estado de ánimo y el tempo; cuanto más específico, más consistentes serán los resultados.
seed	integer	No	Valor mínimo 0. Reutiliza el mismo seed con el mismo prompt para obtener resultados más reproducibles.

prompt es obligatorio: si lo omites, la tarea no se crea en absoluto:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

Si envías cualquier otro campo —duration, negative_prompt, sample_count y campos similares que aceptan otros modelos musicales— la solicitud se rechaza directamente:

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

La duración de la pista de salida la fija el propio modelo; no hay ningún parámetro duration para configurarla.

Consideraciones para producción

Los callbacks son mejores que el sondeo. Salvo para pruebas rápidas, pasa un callback de nivel superior en lugar de sondear en un bucle:

{
  "model": "lyria-3-pro",
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" },
  "input": { "prompt": "..." }
}

Cuando la tarea alcanza un estado terminal (success o fail), hiapi envía un único POST a callback.url; no hace falta mantener un bucle de sondeo activo. Aun así, conserva el sondeo como respaldo por si falla la entrega del callback.

Idempotencia. Si quien llama puede reintentar la misma solicitud, envía la cabecera Idempotency-Key (máximo 255 bytes): los reintentos con la misma key en la misma cuenta devuelven el taskId original en lugar de crear (y facturar) una pista duplicada.

Conservar la salida más de 7 días. El almacenamiento de salida es temp de forma predeterminada (unos 7 días). Establece "storage": "persistent" en el nivel superior al crear la tarea para conservar la pista a largo plazo (se factura por tamaño), o promociona la salida temp más adelante.

Manejo de errores. Una key errónea o no autorizada devuelve HTTP 401:

{"error":{"code":"permission_denied","message":"This API key cannot use the selected model. Please check permissions or use another key.","type":"hiapi_error"}}

Una entrada mal formada devuelve 400 con error_code: INVALID_REQUEST (como se muestra arriba); saldo insuficiente devuelve 402; un Content-Type que no sea JSON devuelve 415. Si encuentras un 503 intermitente, reintenta con retroceso exponencial: indica que la plataforma no está disponible temporalmente, no que tu solicitud sea incorrecta.

Los precios de lyria-3-pro (y de todos los demás modelos de la plataforma) se listan en la página de precios de hiapi, no codificados aquí, ya que los niveles pueden cambiar.

Recursos relacionados

• Referencia del modelo lyria-3-pro: precios y playground de este modelo.
• Crear tarea / Obtener detalles de la tarea (API asíncrona unificada): el contrato compartido de solicitud/respuesta que usa cada modelo en hiapi.
• API de minimax-music-3: guía con curl y Python: otro modelo de texto a música con el que comparar estilos de salida.
• Cómo usar la API de MiniMax Music (minimax-music-1.5): un modelo de generación musical MiniMax anterior, útil para comparar coste y calidad.

Preguntas frecuentes

¿Se puede configurar la duración de la pista generada? No. El schema de input de lyria-3-pro solo acepta prompt y seed; no hay campo duration y la duración de la pista la decide el propio modelo.

¿Admite lyria-3-pro prompts negativos o audio de referencia de estilo? No. A diferencia de otros modelos de la plataforma, el schema de lyria-3-pro se limita estrictamente a prompt y seed; enviar negative_prompt o cualquier campo de audio de referencia devuelve 400 INVALID_REQUEST.

¿En qué formato está el archivo de salida? MP3, devuelto en output[0].url con type igual a "audio". Esa URL es un enlace temporal y, salvo que se establezca "storage": "persistent", caduca según output[0].expireAt.

¿Cómo obtener resultados reproducibles? Usa el mismo prompt y pasa el mismo seed (entero no negativo). Si omites seed, cada llamada puede producir resultados diferentes.

¿Cuál es la forma más rápida de depurar una solicitud que devuelve 400 repetidamente? Lee el message: indica el campo concreto que falta o no es válido. El schema es estricto: enviar campos que este modelo no acepta (por ejemplo, duration, que otros modelos musicales de la plataforma sí aceptan) devuelve 400 con un error de "additional properties not allowed".