Herramientas de música
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).
Para efectos de sonido, una base instrumental de duración exacta o una banda sonora escrita sobre un vídeo que ya tienes, usa generate_sound más abajo.
#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
titleystyleestán rellenados → modo avanzado (custom).promptse ignora para el contenido; usasong_description/lyrics. - Si solo uno de
titleostyleestá definido → inválido; envía ambos o ninguno. - Si no hay título ni estilo → modo simple;
promptes obligatorio.
Modo avanzado — descripción vs letras (no instrumental):
- Elige uno: usa
song_descriptionolyrics, nunca ambos. Enviar ambos se rechaza (no se concatenan). - Solo descripción: tema/ambiente/instrucciones para el modelo; deja
lyricsvacío. - Solo letras: letras completas del usuario; deja
song_descriptionvací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.
<a id="generate_sound"></a>
#generate_sound
Efectos de sonido y música, a partir de una frase o escritos sobre un clip que ya tienes. No sirve para canciones con voz: para eso está generate_music. Todos los modelos de esta herramienta cobran por segundo y las generaciones no se reembolsan, así que cotiza con estimate antes de lanzar.
Elige el modelo según lo que tengas:
| Modelo | Entrada | Resultado |
|---|---|---|
sonilo-text-to-sfx | Una frase | Un efecto de sonido descrito. De 1 a 180 segundos, 5 por defecto. |
sonilo-text-to-music | Una frase | Una pista instrumental de la duración que elijas, nunca con voz. De 5 a 360 segundos, 60 por defecto. Prefiérelo a Suno cuando la pista tenga que encajar en un hueco ya definido. |
sonilo-video-to-sfx | Un vídeo | Efectos ajustados a la imagen, como pista de audio suelta. |
sonilo-video-to-music | Un vídeo | Una banda sonora escrita sobre el montaje, como pista de audio suelta. |
sonilo-video-to-sound | Un vídeo | Efectos y música mezclados, como pista de audio suelta. |
sonilo-video-to-video-sfx | Un vídeo | Igual que sonilo-video-to-sfx, pero devuelve el clip con el sonido ya incluido. |
sonilo-video-to-video-music | Un vídeo | Igual que sonilo-video-to-music, devuelto como clip. |
sonilo-video-to-video-sound | Un vídeo | Igual que sonilo-video-to-sound, devuelto como clip. |
Usa un id -video-to-video-* cuando el usuario quiera recibir un clip terminado, y los ids de solo audio cuando vaya a mezclar el sonido por su cuenta en un editor.
Parámetros:
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
model | string | Sí | Uno de los ids de arriba. |
prompt | string | No | Se traslada al campo que lee el modelo. Los dos modelos *-sound rechazan un prompt suelto; ahí usa music_prompt y sfx_prompt. Máx. 2000 caracteres. |
music_prompt | string | No | Ambiente e instrumentación de la parte musical. |
sfx_prompt | string | No | En qué deben centrarse los efectos. |
video_url | string | Modelos de vídeo | URL HTTPS del clip, de hasta 360 segundos. Para un archivo local, llama a get_upload_url(model_id="<id del modelo>"), deja que el usuario lo suba y luego get_upload_session(token). |
duration_seconds | number | No | Modelos de texto: la duración del resultado. Modelos de vídeo: la duración del clip, solo si no se conoce ya por una subida o por una generación propia. |
preserve_speech | boolean | No | Modelos de vídeo. Conserva en el resultado la voz que ya tiene el clip. Por defecto false. |
ducking | boolean | No | Modelos de vídeo, con preserve_speech activado. Baja el sonido nuevo mientras alguien habla. Por defecto true. |
Una ejecución de vídeo sin ningún prompt es válida, y a menudo da mejor resultado: el modelo escribe a partir de lo que ve.
Facturación: por segundo de clip en los modelos de vídeo (no del resultado) y por segundo de resultado en los de texto. Cada producto tiene una duración mínima facturable: 10 segundos en todo lo que escribe música (incluidos los dos ids *-sound) y 3 segundos en los ids de solo efectos, así que una banda sonora de 6 segundos se cobra como 10. estimate(model=..., reference_video_seconds=<segundos del clip>) aplica el mínimo por ti.
Respuesta: {generation_id, status: "pending"}. Consulta get_status hasta completed o failed. El proveedor no envía callback, así que la consulta es lo que cierra la ejecución; si la abandonas antes, los créditos se quedan reservados.
#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.

