Cómo usar lyria-3.5 a través de la API de hiapi: curl, Python y una solicitud funcional

lyria-3.5 es el modelo de texto a música de hiapi: envía una descripción musical, una letra o ambas cosas y obtén una pista terminada; opcionalmente también puedes incluir un título, una guía de tempo y un control de duración. Esta guía explica en detalle el esquema de entrada, una solicitud que devuelve una pista real y los detalles necesarios para pasar de una prueba puntual a producción.

Qué necesitas preparar

• Una API key de hiapi. Puedes obtenerla en el dashboard: la key empieza por sk-.
• curl o requests de Python. No se necesita SDK; hiapi usa REST puro.

lyria-3.5 se ejecuta sobre la API de tareas asíncronas unificada de hiapi: envías una tarea con POST, recibes un taskId de inmediato y luego consultas el resultado o recibes un callback cuando la pista esté lista.

Esquema de entrada completo

lyria-3.5 acepta mucho más que un simple prompt. Salvo que debes proporcionar al menos uno de prompt o lyrics, todos los campos son opcionales:

Campo	Tipo	Descripción
prompt	string	Género, instrumentos, estado de ánimo, voz, estructura de la canción. Proporciona prompt o lyrics.
lyrics	string	Una frase por línea. Las etiquetas de sección —[Intro], [Verse], [Chorus], [Bridge], [Outro]— van cada una en su propia línea, seguidas de la letra. Numera las secciones repetidas con [Verse 1], [Verse 2].
title	string	Título de la canción generada.
bpm	string	Guía de tempo; debe ser una cadena numérica, por ejemplo "90".
length	integer	Duración solicitada en segundos, 1–240. Sirve para guiar la longitud; la duración real puede variar. Omítelo para no especificarla.
seed	string	Semilla como cadena numérica, por ejemplo "00123". Aunque la seed sea la misma, no se garantiza obtener exactamente el mismo audio.

Dos advertencias previas: bpm y seed son cadenas, no números; envía "90" y no 90, o la API devolverá un 400 (got number, want string). Además, el esquema es estricto: cualquier campo que no esté en la tabla anterior (duration, style, genre, negative_prompt, etc.) devolverá un 400 con additional properties '...' not allowed.

Ejemplo mínimo funcional

1. Crear la 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.5",
    "input": {
      "prompt": "Warm instrumental indie folk, fingerpicked acoustic guitar, soft brushed drums, quiet morning",
      "bpm": "90",
      "length": 30
    }
  }'

Una respuesta correcta llega de inmediato, antes de que la pista se renderice realmente:

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

2. Consultar el resultado

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

Espera unos segundos antes de la primera consulta y luego revisa cada 3–5 segundos. status pasará primero por handling y después alcanzará un estado final. Esta es la respuesta real de la solicitud anterior, unos 100 segundos después:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2",
    "model": "lyria-3.5",
    "status": "success",
    "created": 1789437730,
    "completed": 1789437829,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M2HCSKAP77MTH1ANKQXE1DT2-0.m4a",
        "expireAt": 1790042629
      }
    ]
  }
}

Ten en cuenta que el formato contenedor de la salida puede variar según la solicitud (aquí es .m4a; otros modelos de música de hiapi devuelven .mp3): lee output[0].type/URL en lugar de codificar la extensión de forma fija. Descarga output[0].url a tiempo: la capa de almacenamiento temp predeterminada caduca al cabo de unos 7 días (expireAt es una marca de tiempo Unix). En caso de fallo, status es fail y data.error contendrá { code, message } en lugar de output.

3. Enviar una solicitud basada en letra con 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.5",
    "input": {
        "title": "Carry the Morning",
        "lyrics": (
            "[Verse 1]\n"
            "Light through the window, coffee still warm\n"
            "[Chorus]\n"
            "Carry the morning, carry it slow\n"
        ),
        "bpm": "96",
        "length": 45,
    },
}

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

status = None
while status not in ("success", "fail"):
    time.sleep(4)
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = poll["data"]["status"]

if status == "success":
    print(poll["data"]["output"][0]["url"])
else:
    print(poll["data"]["error"])

Según necesites una pista instrumental o con voz, cambia lyrics por prompt (o envía ambos).

Consideraciones para producción

• Usa callbacks en lugar de consultas periódicas.Añade un objeto callback de nivel superior: {"url": "https://yourapp.com/hook", "when": "final"}. when solo acepta "final": recibirás una llamada cuando la tarea alcance un estado final, no actualizaciones de progreso.
• Idempotencia.La API de tareas no acepta claves de idempotencia proporcionadas por el cliente, así que evita problemas con los reintentos en la capa de aplicación: persiste el taskId en cuanto lo recibas y comprueba el estado de la tarea antes de reintentar, para no enviar solicitudes duplicadas.
• Errores.Una API key ausente o no válida devuelve HTTP 401 y error_code: "permission_denied". Infringir el esquema devuelve HTTP 400 y error_code: "INVALID_REQUEST", con un mensaje que indica el campo problemático; esto ayuda a detectar antes de producción un duration sobrante o un bpm de tipo numérico.
• Almacenamiento.Tras una consulta correcta o un callback, transfiere output[0].url a tu propio almacenamiento de inmediato; no dependas de la capa temp más allá de su expireAt.

Lecturas relacionadas

• Tutorial de la API de lyria-3-pro: otro modelo Lyria de hiapi; si no necesitas letra ni control de tempo, su esquema es más sencillo y solo requiere un prompt.
• Guía de la API de MiniMax Music: otro modelo de texto a música de hiapi, con su propio conjunto de opciones de letra y muestreo.
• Referencia del modelo lyria-3.5: documentación autoritativa de los parámetros.
• Precios de hiapi: tarifas actuales de cada modelo.

Preguntas frecuentes

¿Necesito enviar prompt y lyrics a la vez?No: la API solo exige al menos uno de los dos. Enviar solo prompt produce una pista instrumental; enviar solo lyrics produce una pista impulsada por completo por la letra; o puedes enviar ambos.

¿Qué formato de audio devuelve lyria-3.5?Varía según la solicitud: revisa output[0].type y la extensión de la URL; no asumas que sea .mp3 o .m4a.

¿Puedo forzar un tempo exacto?bpm es una guía, no una restricción estricta, y debe enviarse como cadena ("90", no 90).

¿Cuánto puede durar la pista generada?length acepta de 1 a 240 segundos, pero solo guía al modelo y no garantiza una duración exacta: comprueba la duración real del archivo devuelto.

¿La misma seed me dará la misma pista dos veces?No. seed es una cadena numérica que se usa para ajustar ligeramente la generación, pero la documentación de hiapi indica explícitamente que no se garantiza que el audio sea idéntico.

¿Qué ocurre si envío un campo no reconocido, como genre o duration?El esquema es estricto: recibirás un 400 y additional properties '<field>' not allowed, en lugar de que ese campo se ignore silenciosamente.