API de añadir instrumentación

Actualizado el 2026-09-18 · equipo de Suno-API

Descripción del endpoint

Añadir instrumentación re-arregla una canción existente, añade instrumentos o genera una nueva estructura de acompañamiento.

Endpoint: POST /api/music/add-instrumental

Facturación: De pago, facturada según el modelo solicitado; el importe realmente cobrado sigue la configuración de precios del back-office.

Max Mode / Variety: este endpoint admite los parámetros opcionales max_mode y variety (0-4). Con max_mode activado, esta llamada se factura al doble; variety no cuesta nada extra. Qué significan y cómo enviarlos está en la sección «Parámetros avanzados» del Resumen de la nueva API.

Modelo recomendado: suno-v6. Se pueden usar suno-v6, suno-v6-wild y suno-v6-mini.

Tiempos de espera y timeouts (importante): es un endpoint síncrono — el pedido solo se acepta y se entrega a generación cuando llega la respuesta. Según lo medido, la mayoría de las peticiones responden en 1-3 segundos, alrededor del 10% tardan más de 30 segundos y la más lenta ronda los 230 segundos. Configura el timeout del cliente en 300 segundos o más; no recibir respuesta no significa que no se haya generado nada, y no reintentes justo después de un timeout (eso duplica el pedido y vuelve a cobrar). Si la conexión se cayó, confírmalo más tarde con GET /api/music/songs. Consulta «Tiempos de espera y configuración de timeout» en el Resumen de la nueva API.

Autenticación

Parámetros de la petición

Ejemplo de petición

curl -X POST https://www.suno-api.io/api/music/add-instrumental \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "source_clip_id": "source_song_id",
    "lyrics": "",
    "style_tags": "cinematic, strings, acoustic guitar",
    "song_title": "Versión con acompañamiento mejorado",
    "audio_weight": 1,
    "wait_completion": false
  }'

Respuesta

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "result_song_id",
        "song_title": "Versión con acompañamiento mejorado",
        "status": "pending"
      },
      {
        "song_id": "result_song_id_2",
        "song_title": "Versión con acompañamiento mejorado",
        "status": "pending"
      }
    ]
  }
}

Una llamada devuelve 2 resultados (se factura como 2 canciones); el ejemplo muestra 2. Guíate por la longitud del array clips y no fijes un número en el código. Guarda clips[].song_id y sondea la API de consulta de canciones hasta completed. Cuando termine, puedes reproducir o descargar con audio_url; consulta la API de generación/obtención de WAV y los endpoints de descarga.

Notas

• source_clip_id debe ser un ID real, completado y accesible con la clave de API actual; no se puede usar un ID de reserva pending:.
• Añadir instrumentación no es un cover; para un cover usa la API de cover desde un clip de origen.
• Para añadir un instrumento o una pista concreta a una canción existente, usa la API de añadir pista.