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.

    ModoCuándo usarloCómo lo decide la API
    SimpleIdea 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ámetroTipoObligatorioDescripción
    promptstringSíUna sola descripción de la música; máx. 400 caracteres.
    instrumentalbooleanNoSi true, solo instrumental (sin voz). Por defecto: false.
    modelstringNoV6 (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ámetroTipoObligatorioDescripción
    titlestringSíTítulo de la canción; máx. 80 caracteres.
    stylestringSíEstilo / género / etiquetas; máx. 1000 caracteres.
    vocal_genderstringSí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_descriptionstringXOR con lyricsDe qué trata la canción (tema, ambiente). Máx. 5000 caracteres. Omite si usas lyrics.
    lyricsstringXOR con song_descriptionLetras completas si el usuario las aportó. Máx. 5000 caracteres. Omite si usas song_description.
    instrumentalbooleanNoPor defecto false. Si true, solo song_description.
    negative_tagsstringNoEstilos o elementos a evitar; máx. 200 caracteres.
    style_weightnumberNoPor defecto 0.65 (como la web).
    weirdness_constraintnumberNoPor defecto 0.65.
    audio_weightnumberNoPor defecto 0.65.
    modelstringNoMismo 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:

    ModeloEntradaResultado
    sonilo-text-to-sfxUna fraseUn efecto de sonido descrito. De 1 a 180 segundos, 5 por defecto.
    sonilo-text-to-musicUna fraseUna 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-sfxUn vídeoEfectos ajustados a la imagen, como pista de audio suelta.
    sonilo-video-to-musicUn vídeoUna banda sonora escrita sobre el montaje, como pista de audio suelta.
    sonilo-video-to-soundUn vídeoEfectos y música mezclados, como pista de audio suelta.
    sonilo-video-to-video-sfxUn vídeoIgual que sonilo-video-to-sfx, pero devuelve el clip con el sonido ya incluido.
    sonilo-video-to-video-musicUn vídeoIgual que sonilo-video-to-music, devuelto como clip.
    sonilo-video-to-video-soundUn vídeoIgual 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ámetroTipoObligatorioDescripción
    modelstringSíUno de los ids de arriba.
    promptstringNoSe 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_promptstringNoAmbiente e instrumentación de la parte musical.
    sfx_promptstringNoEn qué deben centrarse los efectos.
    video_urlstringModelos de vídeoURL 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_secondsnumberNoModelos 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_speechbooleanNoModelos de vídeo. Conserva en el resultado la voz que ya tiene el clip. Por defecto false.
    duckingbooleanNoModelos 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ámetroTipoObligatorioDescripción
    generation_idstringSí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.