API de ElevenLabs Music en HiAPI: genera música con curl, Python y recetas de prompts

Por qué llamar a elevenlabs/music-v2.5 a través de HiAPI

Si quieres añadir generación de música a tu producto, el camino más rápido no suele ser el más limpio. Conectar el backend directamente al proveedor del modelo significa que tú te encargas de la configuración de cuenta de ese proveedor, del esquema de autenticación, de la semántica de reintentos y de la estructura de las solicitudes. Cada nuevo modelo que adoptas añade otro conjunto de estas decisiones, y cada experimento deja una rama de integración.

Llamar a elevenlabs/music-v2.5 a través de HiAPI cambia la forma de este trabajo. Solo necesitas una URL base, una cabecera de autenticación y una convención de solicitud que se mantiene estable al cambiar entre modelos. El identificador del modelo (elevenlabs/music-v2.5) es solo una cadena en el cuerpo de la solicitud, así que cambiar entre modelos de música, o probar un segundo modelo para comparar, requiere cambiar una línea en lugar de importar un SDK nuevo.

Para los desarrolladores que eligen cómo integrarse, hay tres ventajas prácticas que merecen atención:

• Un único plano de gestión de credenciales. La gestión de claves, la rotación y el aislamiento de entornos (desarrollo/staging/producción) se centralizan en un solo lugar en vez de multiplicarse por proveedor.
• Patrones de solicitud portables. Los fragmentos de curl y Python de abajo coinciden con los que usarías para otros modelos en HiAPI. Aprendes el patrón una vez y basta.
• Uso centralizado en un solo lugar. La generación de música se factura por duración de salida; tenerla junto al uso de otros modelos significa seguir los costos en un único panel en lugar de enfrentarte a facturas dispersas.

El costo es que pasas por una capa de abstracción, así que las rarezas propias del proveedor se normalizan. Para la primera integración y la mayoría de los casos de producción, esa normalización es justo lo que quieres. Cuando necesites entender el comportamiento concreto del modelo, la página de detalles del sitio es la fuente autorizada.

Preparación antes de la primera solicitud de música

Confirma cuatro cosas antes de escribir código, para que la primera llamada devuelva audio en lugar de un 401 o un error de validación.

1. Clave de API

Necesitas una clave de API de tu cuenta de HiAPI. Trátala como cualquier otro secreto: guárdala en una variable de entorno, nunca la confirmes en el código fuente y usa claves distintas para desarrollo local y producción, de modo que puedas revocar una sin afectar a la otra.

export HIAPI_API_KEY="your_key_here"

2. URL base y convención de endpoint

Todas las llamadas a modelos usan la misma URL base; el modelo se identifica dentro de la solicitud, no en la ruta. Mantén una constante para la URL base en tu proyecto, así, si tu entorno es distinto, solo cambias un lugar.

3. Un prompt escrito en lenguaje natural

elevenlabs/music-v2.5 acepta un prompt de texto que describe la música que quieres. No necesitas partituras ni archivos MIDI. Una o dos frases que indiquen género, instrumentación, estado de ánimo y duración prevista bastan para empezar. Las secciones siguientes ofrecen recetas reutilizables.

4. Expectativas correctas sobre la salida

La generación de música devuelve audio, no una partitura en JSON. Planifica cómo manejarás la carga de la respuesta: escribir a un archivo durante el desarrollo, transmitir o almacenar en producción. Decide de antemano cuánto quieres que dure el fragmento, porque la duración afecta tanto a la solicitud como a la facturación.

Una cosa más antes de la primera solicitud: consulta los límites de velocidad y el precio actuales de elevenlabs/music-v2.5 en el panel de precios del sitio, en lugar de codificar suposiciones en el código. Los precios y los límites cambian, y tu integración debe leerlos como configuración, no incrustarlos como constantes del script.

Hacer la primera llamada con curl

Empieza con curl porque elimina todas las capas entre tú y la solicitud HTTP. Si la llamada con curl funciona, cualquier fallo en la aplicación es problema de la aplicación, no de la API.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/music-v2.5",
    "messages": [
      {
        "role": "user",
        "content": "Instrumental lo-fi hip hop, warm vinyl texture, mellow electric piano, soft brushed drums, 80 BPM, relaxed late-night mood, about 30 seconds."
      }
    ]
  }'

Esto es lo que hace cada parte:

• -sS silencia la salida de progreso pero sigue mostrando errores. Útil cuando pegas la salida en un archivo.
• La URL es el endpoint unificado. Observa que el nombre del modelo no aparece en la ruta, sino en el cuerpo de la solicitud.
• Authorization: Bearer $HIAPI_API_KEY lee la clave del entorno, así no queda en texto plano en el historial del shell. En Windows, define la variable con set o con la sintaxis $env: de PowerShell, según corresponda.
• Content-Type: application/json es obligatorio; el endpoint no acepta codificación de formulario.
• model es el identificador exacto elevenlabs/music-v2.5. Un error tipográfico aquí produce un error de modelo no encontrado en lugar de un fallo genérico, lo cual ayuda a depurar.
• messages pasa tu prompt como contenido del mensaje de usuario. Pon el prompt en un solo mensaje; los prompts largos y estructurados funcionan mejor que repartidos en varios.

El cuerpo de la respuesta contiene el audio generado y metadatos sobre la solicitud. Durante el desarrollo, redirige la salida a un archivo para poder escuchar el resultado de inmediato:

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json -o response.json

Poner la carga en request.json y leerla con -d @request.json es un hábito que conviene adoptar pronto. Hace que las solicitudes sean comparables y revisables, y fáciles de repetir cuando cambias un parámetro a la vez.

Repetir la llamada en Python

Una vez que la llamada con curl devuelve audio, migra a Python. El objetivo no es solo un script que funcione, sino una función que puedas invocar desde una cola de tareas, un manejador de API o un notebook sin desviaciones por copiar y pegar.

import json
import os
import urllib.request

BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
MODEL = "elevenlabs/music-v2.5"

def generate_music(prompt: str, timeout: int = 120) -> dict:
    """Envía un prompt de música a elevenlabs/music-v2.5 a través de HiAPI."""
    api_key = os.environ.get("HIAPI_API_KEY")
    if not api_key:
        raise RuntimeError("HIAPI_API_KEY is not set")

    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": prompt}],
    }

    request = urllib.request.Request(
        BASE_URL,
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request, timeout=timeout) as response:
        return json.loads(response.read().decode("utf-8"))

if __name__ == "__main__":
    result = generate_music(
        "Cinematic orchestral swell, strings and low brass, hopeful build, "
        "no percussion, about 20 seconds."
    )
    print(json.dumps(result, indent=2)[:500])

A medida que la función crezca, hay varias decisiones que conviene conservar:

• Prioriza la biblioteca estándar. urllib evita dependencias cambiantes en el tutorial. Si tu proyecto ya usa requests o httpx, la conversión es mecánica: pasa json=payload, headers=headers y timeout.
• El timeout es obligatorio. La generación de música tarda más que las completaciones de chat. Define un timeout explícito y no dependas de los valores por defecto. Elige un valor mayor que el tiempo de generación esperado para el fragmento más largo que solicites.
• Lee la clave en el momento de la llamada, no en el de la importación, para que el mismo módulo funcione tanto en local como en un contenedor donde el entorno se inyecta en tiempo de ejecución.
• Devuelve datos estructurados en lugar de imprimir cadenas. Que quien llama decida si escribe el audio en disco, lo sube a un almacenamiento de objetos o lo reenvía al cliente.

Antes de construir nada sobre ellas, confirma que la función de Python y la llamada con curl producen resultados equivalentes para el mismo prompt. Esa consistencia es tu línea base de regresión.

Recetas de prompts para estilo, estado de ánimo y duración

Los prompts de música funcionan mejor cuando responden a tres preguntas en orden: qué género e instrumentación, qué tono emocional y cuánto dura. Los prompts vagos producen salidas genéricas; los prompts demasiado largos diluyen los descriptores importantes. El objetivo es una frase densa o tres cláusulas cortas.

Usa estas como puntos de partida listos para copiar y pegar, y ajusta una sola dimensión a la vez.

Recetas centradas en el estilo

• Solo piano, felt hammers, close-miked, slow arpeggios in the style of a modern film score.
• Upbeat synthwave, analog bass, gated reverb drums, arpeggiated lead, 120 BPM.
• Acoustic folk ensemble, fingerpicked guitar, upright bass, light tambourine, organic room sound.
• Ambient drone, layered pads, no rhythm section, slowly evolving texture.

Recetas centradas en el estado de ánimo

• Warm and nostalgic, like a summer evening, major key, gentle dynamics.
• Tense and minimal, low pulsing bass, sparse percussion, unresolved harmony.
• Playful and bright, staccato strings, bouncy rhythm, light-hearted.
• Melancholic and spacious, reverb-heavy, sparse piano, slow tempo.

Recetas centradas en la duración

La duración debe indicarse en el prompt como un objetivo explícito y debe ser coherente con el arreglo. Una solicitud de 15 segundos con una introducción lenta y un final largo se cortará de forma abrupta.

• ... about 15 seconds, short intro, no outro, ends cleanly.
• ... about 30 seconds, one clear section, loopable ending.
• ... about 60 seconds, intro, main section, and a natural fade.

Ejemplo combinado

Lo-fi hip hop for focus, dusty vinyl crackle, soft electric piano, brushed drums, 80 BPM, calm and unhurried, about 30 seconds, loopable.

Cuando la salida no cumple lo esperado

Ajusta una sola variable por intento, así sabrás exactamente qué cambió el resultado.

• Demasiado genérico: sustituye las palabras de estado de ánimo por instrumentación y tempo concretos. «Energetic» es más débil que «driving 16th-note bass at 128 BPM».
• Demasiado recargado o desordenado: elimina instrumentos de forma explícita (no drums, no vocals, sparse arrangement) en lugar de añadir más descriptores positivos.
• La duración no se siente bien: si el fragmento se corta de golpe, pide un objetivo más corto y un final claro; si se siente apresurado, reduce el número de secciones solicitadas.
• Deriva de estilo: mueve el género y la instrumentación al principio del prompt. Los tokens iniciales tienen más peso.

Mantén en el repositorio un pequeño archivo de prompts que registre las recetas que funcionan. Ese archivo vale más que cualquier fragmento generado individualmente, porque convierte la escritura de prompts en un artefacto de ingeniería repetible.

Errores comunes y cómo corregirlos

La mayoría de las primeras integraciones fallan de unas pocas formas predecibles. Repasa esta lista antes de empezar a adivinar.

Fallos de autenticación

Un 401 casi siempre significa que la cabecera está mal formada o que falta la clave en el entorno del proceso. Comprueba si hay espacios extra después de Bearer, si la clave se cargó desde el archivo .env equivocado, o si el export se ejecutó en otra sesión distinta a la del script. Imprime la longitud de la clave (no la clave) para confirmar que está rellenada.

Desajuste del identificador del modelo

Un error de modelo no encontrado o de validación suele significar que la cadena model no coincide exactamente. elevenlabs/music-v2.5 distingue mayúsculas de minúsculas e incluye una barra. Si lo copiaste de una ventana de chat, comprueba si quedaron comillas tipográficas o saltos de línea residuales.

Cuerpo de solicitud mal formado

Si curl funciona pero Python no, la diferencia casi siempre es de serialización. Pasar un dict de Python donde se espera una cadena JSON, codificar dos veces con json.dumps u olvidar Content-Type: application/json producen errores de parseo en el servidor que parecen no tener relación con la causa real. Registra el cuerpo exacto que envía tu código y compáralo carácter por carácter con la carga de curl que funciona.

Timeouts en fragmentos largos

Duraciones mayores requieren tiempos de generación mayores. Un timeout de cliente adecuado para solicitudes de chat truncará las solicitudes de música más largas. Aumenta el timeout específicamente para este endpoint y añade reintentos con retroceso solo para fallos a nivel de conexión; nunca reintentes a ciegas solicitudes que ya podrían haberse facturado.

Longitud y contenido del prompt

Los prompts extremadamente largos, o los que contienen instrucciones sobre la propia API, suelen producir música peor. Que el prompt trate solo sobre música. Si un prompt que funcionaba ayer deja de funcionar, redúcelo al esqueleto de estilo/estado de ánimo/duración y vuelve a construirlo.

Tratar la respuesta como texto

El endpoint devuelve datos de audio, no una transcripción legible. Escribir el cuerpo crudo de la respuesta en un archivo .txt y luego preguntarse por qué no se reproduce es un error común del primer día. Guárdalo con la extensión de audio correcta y verifica que el archivo se abre en un reproductor antes de seguir construyendo.

Cuando el error no sea claro, reprodúcelo con la solicitud curl más pequeña posible. Así aíslas si el problema está en el contrato de la API o en tu código.

De una llamada de prueba a un flujo de trabajo repetible

Una llamada de prueba exitosa es el punto de partida, no la integración. Usa esta lista para convertirla en algo con lo que el equipo pueda contar.

• Configuración externalizada. La URL base, el identificador del modelo, los timeouts y el objetivo de duración por defecto van a configuración, no a literales de cadena dispersos. Los valores específicos de cada entorno vienen del entorno.
• Cliente centralizado. Una función o una clase de cliente ligera se encarga de la solicitud. Ningún módulo debería construir por su cuenta llamadas HTTP al endpoint de música, o acabaréis divergiendo en cabeceras y manejo de errores.
• Errores tratados por categoría. Distingue autenticación, validación, timeout y errores del servidor. Reintenta solo errores transitorios, con retroceso y un límite máximo. Nunca reintentes solicitudes que ya podrían haber producido salida y haberse facturado.
• Almacenamiento correcto del audio. Escribe en almacenamiento de objetos con claves deterministas, guarda el prompt junto al recurso generado y registra el identificador del modelo. Reproducir resultados más adelante depende de saber exactamente qué se solicitó entonces.
• Duración como parámetro de primera clase. Como la facturación sigue la duración de salida, indica el objetivo de duración en las plantillas de prompt y regístralo por solicitud, para que los informes de costos se alineen con el uso.
• Biblioteca de prompts. Mantén las recetas validadas bajo control de versiones, con una nota breve sobre para qué sirve cada una. Los nuevos miembros del equipo empiezan con prompts que funcionan, no adivinando.
• Separar rutas síncronas y asíncronas. La generación puede ser lenta. Para funciones de cara al usuario, envía un trabajo, persiste la solicitud y deja que un worker llame al modelo. El manejador HTTP no debe permanecer abierto durante toda la generación.
• Validar con una prueba de humo. Una prueba que envía un prompt corto fijo y comprueba que la respuesta de audio tiene el formato correcto detecta pronto la deriva de credenciales y de contrato.

Cuando estés listo para profundizar en parámetros y límites, la página del modelo elevenlabs/music-v2.5 en HiAPI es donde consultar las capacidades actuales antes de codificar suposiciones.