Herramientas de música

Kubeez

Genera pistas musicales completas. Todos los trabajos de música son asíncronos: llama a generate_music y luego consulta get_status hasta que status sea completed (o failed).

#Cómo elegir: simple vs avanzado

La herramienta generate_music tiene dos modos excluyentes. El agente debe elegir uno según lo que pida el usuario.

Modo	Cuándo usarlo	Cómo lo decide la API
Simple	Idea rápida en un solo texto: género, ambiente, instrumentos. Sin título fijo, etiquetas de estilo, letras ni género vocal.	No establezcas `title` ni `style` (déjalos vacíos). Proporciona un `prompt` no vacío (máx. 400 caracteres).
Avanzado (personalizado)	El usuario quiere título, estilo (género/etiquetas), género vocal (o aleatorio), y o bien descripción o letras (no ambas), opcionalmente negative_tags (qué evitar).	Establece tanto `title` como `style` como cadenas no vacías. `vocal_gender` es obligatorio (`m`, `f` o `random`). Usa exactamente uno de `song_description` o `lyrics` cuando no sea instrumental (ver abajo).

Reglas:

Si ambos title y style están rellenados → modo avanzado (custom). prompt se ignora para el contenido; usa song_description / lyrics.
Si solo uno de title o style está definido → inválido; envía ambos o ninguno.
Si no hay título ni estilo → modo simple; prompt es obligatorio.

Modo avanzado — descripción vs letras (no instrumental):

Elige uno: usa song_description o lyrics, nunca ambos. Enviar ambos se rechaza (no se concatenan).
Solo descripción: tema/ambiente/instrucciones para el modelo; deja lyrics vacío.
Solo letras: letras completas del usuario; deja song_description vacío.

Modo avanzado — instrumental: pon instrumental: true y proporciona solo song_description; no envíes lyrics.

Usa get_models con model_type=music para IDs de modelos y costes en créditos.

#Modelos

La generación de música funciona con Suno. Valores de model admitidos (simple y avanzado): V6, V6_WILD, V6_MINI (mostrados en la aplicación como V6, V6 Wild y V6 Mini). Los tres cuestan lo mismo, así que la elección es de carácter, no de precio: V6 tiene el mayor detalle y las voces más naturales, V6_WILD va más lejos para un resultado más audaz, V6_MINI es la vía rápida y ligera.

Si se omite model, aplica el valor por defecto V6. Todas las versiones anteriores (V4, V4_5, V4_5PLUS, V4_5ALL, V5, V5_5) fueron retiradas por el proveedor. Una petición que nombre una de ellas la atiende V6 al mismo precio en lugar de rechazarse, así que una integración existente sigue funcionando, pero esos identificadores ya no forman parte del conjunto admitido.

#generate_music

#Parámetros modo simple

Parámetro	Tipo	Obligatorio	Descripción
`prompt`	string	Sí	Una sola descripción de la música; máx. 400 caracteres.
`instrumental`	boolean	No	Si `true`, solo instrumental (sin voz). Por defecto: `false`.
`model`	string	No	`V6` (por defecto), `V6_WILD` o `V6_MINI`.

No envíes title, style ni vocal_gender en modo simple (déjalos vacíos).

Ejemplo — simple, con voz:

{
  "prompt": "Canción pop alegre sobre el verano",
  "instrumental": false,
  "model": "V6"
}

Ejemplo — simple, instrumental:

{
  "prompt": "Música orquestal épica de fondo",
  "instrumental": true
}

#Parámetros modo avanzado

Parámetro	Tipo	Obligatorio	Descripción
`title`	string	Sí	Título de la canción; máx. 80 caracteres.
`style`	string	Sí	Estilo / género / etiquetas; máx. 1000 caracteres.
`vocal_gender`	string	Sí	`m`, `f` o `random` (alias: `male`/`female`; `random` = elige el proveedor). En instrumental sigue siendo obligatorio en la API pero no aplica a la voz.
`song_description`	string	XOR con `lyrics`	De qué trata la canción (tema, ambiente). Máx. 5000 caracteres. Omite si usas `lyrics`.
`lyrics`	string	XOR con `song_description`	Letras completas si el usuario las aportó. Máx. 5000 caracteres. Omite si usas `song_description`.
`instrumental`	boolean	No	Por defecto `false`. Si `true`, solo `song_description`.
`negative_tags`	string	No	Estilos o elementos a evitar; máx. 200 caracteres.
`style_weight`	number	No	Por defecto 0.65 (como la web).
`weirdness_constraint`	number	No	Por defecto 0.65.
`audio_weight`	number	No	Por defecto 0.65.
`model`	string	No	Mismo conjunto que en modo simple.

Requisito de contenido (avanzado, no instrumental): exactamente uno de song_description o lyrics debe estar relleno (el otro omitido o vacío).

Ejemplo — avanzado solo con descripción:

{
  "title": "Neon Midnight",
  "style": "synthwave, años 80, bajo pulsante, nostálgico",
  "vocal_gender": "random",
  "song_description": "Una canción sobre conducir de noche por la ciudad con reflejos de neón",
  "model": "V6"
}

Ejemplo — avanzado solo con letras:

{
  "title": "Morning Light",
  "style": "folk acústico, guitarra suave, cálido",
  "vocal_gender": "f",
  "lyrics": "[Verso 1] ... [Estribillo] ..."
}

Respuesta: Incluye generation_id, status (p. ej. pending), a menudo estimated_time_seconds. Consulta con get_status.

#get_status

Comprueba el estado de una generación musical y obtén las URLs cuando termine.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`generation_id`	string	Sí	ID devuelto por generate_music.

Respuesta: Incluye status, progress y al completarse un array songs. Cada canción suele tener id, title, audio_url, stream_url, cover_image_url, duration, lyrics, style.

Consulta Limitaciones para límites de uso y créditos.