API de descarga y previsualización de medios de canciones

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

Descripción del endpoint

Este grupo de endpoints separa «obtener una dirección de medios» de «descargar el archivo de verdad»:

• Para obtener una dirección que puedas reproducir o descargar directamente (por ejemplo para meterla en tu propio reproductor o copiarla a un almacenamiento de objetos): usa POST /api/music/download-url, o el GET /api/music/download que ya viene en las respuestas.
• Para que el navegador guarde el archivo en disco: usa POST /api/music/download-file (un solo archivo) o POST /api/music/download-all (empaquetado).
• Si la canción aún se está generando y quieres escucharla antes: usa POST /api/music/generation-stream-url.

Facturación: Todo gratis. La descarga y la previsualización solo leen medios que la plataforma ya aloja; no llaman a Suno y no se cobran.

Modelo recomendado: suno-v6. Puedes usar suno-v6, suno-v6-wild o suno-v6-mini.

Autenticación

Tipos de medios admitidos (kind)

1) Obtener una dirección de medios

curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "song_id",
    "kind": "song",
    "url": "https://media.suno-api.io/assets/song_id-mp3.mp3",
    "nav_url": "https://media.suno-api.io/assets/song_id-mp3.mp3?...&response-content-disposition=attachment..."
  }
}

url sirve para reproducir o copiar por tu cuenta; nav_url lleva Content-Disposition: attachment, lo que permite pegarla directamente en la barra de direcciones del navegador para descargar (útil cuando algunos navegadores móviles no admiten la descarga por blob).

⚠️ Validez de la dirección: 7 días, copia el archivo a tiempo

url / nav_url apuntan al almacenamiento de objetos de la plataforma y caducan por defecto a los 7 días (los archivos se reclaman y la dirección antigua devuelve 404). Copia los archivos a tu propio almacenamiento dentro de esos 7 días.

Tras caducar no hace falta regenerar la canción: vuelve a llamar a POST /api/music/download-url (o pasa refresh: true) para obtener direcciones nuevas y válidas de esa canción. Este grupo de endpoints es gratis y no añade ningún cargo.

2) Descargar un solo archivo directamente

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}' \
  -o song.mp3

El cuerpo de la respuesta es un flujo de archivo (no JSON) y Content-Disposition ya incluye el nombre del archivo. La letra y la letra con marcas de tiempo solo se pueden obtener con este endpoint (download-url devuelve solo direcciones de medios, no la letra). El archivo .lrc actualmente solo se admite en algunas canciones; si devuelve success:false, genera el .lrc tú mismo con la API de letras con marcas de tiempo como se explica en la sección siguiente, y no reintentes.

Cómo obtener letras con marcas de tiempo (.lrc)

Se recomiendan dos pasos, y sirven para cualquier canción:

Paso 1: obtener la línea de tiempo palabra por palabra (gratis)

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "suno-v6", "song_id": "song_id"}'

La respuesta es un array directo (sin envoltorio data); cada elemento tiene la forma {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word ya contiene saltos de línea, así que puedes separarlo por líneas; para el significado de los campos, el filtrado de tramos instrumentales y otras advertencias consulta la API de letras con marcas de tiempo («Campos» y «Notas de uso»).

Paso 2: construir el .lrc tú mismo a partir de start_s (formato de tiempo [mm:ss.cc])

def to_lrc(segments):
    lines = []
    for seg in segments:
        text = seg["word"].strip()
        if not text:
            continue
        start = max(0.0, float(seg["start_s"]))
        cs = int(start * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

GET /api/music/download?song_id=<id>&kind=lrc también puede descargar directamente el .lrc generado por el servidor, pero actualmente solo se admiten algunas canciones: si devuelve success:false, genéralo tú mismo como se explica arriba — no hace falta reintentar y la facturación no se ve afectada.

3) Descarga empaquetada

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}' \
  -o songs.zip

Usa song_id (uno solo) o song_ids (lote, hasta 50 entradas). El cuerpo de la respuesta es un flujo ZIP.

4) Dirección de descarga estable

GET /api/music/download?song_id=<id>&kind=<kind> es el punto de entrada de descarga que aparece directamente en las respuestas de canción. Acepta tanto una clave de API como una sesión de navegador, se comporta igual que download-file y es adecuado para dejarlo fijo en un cliente o un reproductor de terceros.

5) Escucha previa durante la generación

curl -X POST https://www.suno-api.io/api/music/generation-stream-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}'

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "song_id": "song_id_1",
        "url": "https://media.suno-api.io/assets/song_id_1-mp3.mp3",
        "expires_at": 0,
        "content_type": "audio/mpeg",
        "playable_until_completed": false,
        "mode": "mp3",
        "ranges": true
      }
    ]
  }
}

Un playable_until_completed igual a true indica que es una dirección de escucha temporal de una canción en generación; cambia a la dirección definitiva cuando la canción termine. Si una canción falla, ese elemento lleva un campo error y las demás se devuelven con normalidad.

Notas

• Todos los endpoints devuelven únicamente direcciones de medios alojados por la plataforma; nunca devuelven la fuente cifrada de Suno ni una dirección firmada temporal.
• Las direcciones no son permanentes: copia los archivos tú mismo si necesitas conservarlos a largo plazo; usa download-file cuando necesites el archivo original en disco.
• El MIDI de un stem requiere que la separación de ese stem haya terminado; si no, se devuelve un error.