API de téléchargement et d'écoute des médias de morceaux

Mis à jour le 2026-09-18 · équipe Suno-API

Description du point d'accès

Ce groupe de points d'accès sépare « obtenir une adresse de média » de « télécharger réellement le fichier » :

• Pour obtenir une adresse directement lisible ou téléchargeable (par exemple pour l'intégrer à votre propre lecteur ou la copier vers un stockage objet) : utilisez POST /api/music/download-url, ou le GET /api/music/download déjà fourni dans les réponses.
• Pour que le navigateur enregistre le fichier sur le disque : utilisez POST /api/music/download-file (fichier unique) ou POST /api/music/download-all (archive).
• Si le morceau est encore en cours de génération et que vous voulez l'écouter d'abord : utilisez POST /api/music/generation-stream-url.

Facturation : Tout est gratuit. Le téléchargement et l'écoute ne font que lire des médias déjà hébergés par la plateforme ; ils n'appellent pas Suno et ne sont pas facturés.

Modèle recommandé : suno-v6. Vous pouvez utiliser suno-v6, suno-v6-wild ou suno-v6-mini.

Authentification

Types de médias pris en charge (kind)

1) Obtenir une adresse de média

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 sert à la lecture ou à la copie de votre côté ; nav_url porte Content-Disposition: attachment, ce qui permet de la coller directement dans la barre d'adresse du navigateur pour télécharger (utile quand certains navigateurs mobiles ne gèrent pas le téléchargement par blob).

⚠️ Validité de l'adresse : 7 jours — copiez le fichier à temps

url / nav_url pointent vers le stockage objet de la plateforme et expirent par défaut au bout de 7 jours (les fichiers sont récupérés et l'ancienne adresse renvoie 404). Copiez-les dans votre propre stockage pendant ces 7 jours.

Après expiration, inutile de régénérer le morceau : rappelez POST /api/music/download-url (ou passez refresh: true) pour obtenir de nouvelles adresses valides pour ce morceau. Ce groupe de points d'accès est gratuit et n'entraîne aucun frais supplémentaire.

2) Télécharger directement un fichier unique

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

Le corps de la réponse est un flux de fichier (pas du JSON) et Content-Disposition contient déjà le nom du fichier. Les paroles et les paroles horodatées ne s'obtiennent qu'avec ce point d'accès (download-url ne renvoie que des adresses de médias, pas les paroles). Le fichier .lrc n'est actuellement pris en charge que pour certains morceaux ; s'il renvoie success:false, générez le .lrc vous-même avec l'API de paroles horodatées comme dans la section suivante, sans réessayer.

Comment obtenir des paroles horodatées (.lrc)

Deux étapes sont recommandées, et elles fonctionnent pour n'importe quel morceau :

Étape 1 : récupérer la timeline mot par mot (gratuit)

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 réponse est un tableau brut (sans enveloppe data) ; chaque élément a la forme {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word contient déjà des sauts de ligne, vous pouvez donc le découper par ligne ; pour le sens des champs, le filtrage des passages instrumentaux et d'autres mises en garde, voir les « Champs » et les « Notes d'utilisation » de l'API de paroles horodatées.

Étape 2 : construire vous-même le .lrc à partir de start_s (format de temps [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 permet aussi de télécharger directement le .lrc généré par le serveur, mais actuellement seuls certains morceaux sont pris en charge : si la réponse est success:false, générez-le vous-même comme ci-dessus — inutile de réessayer, et la facturation n'est pas affectée.

3) Téléchargement groupé

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

Utilisez soit song_id (un seul), soit song_ids (lot, jusqu'à 50 entrées). Le corps de la réponse est un flux ZIP.

4) Adresse de téléchargement stable

GET /api/music/download?song_id=<id>&kind=<kind> est le point d'entrée de téléchargement fourni directement dans les réponses de morceau. Il accepte à la fois une clé d'API et une session de navigateur, se comporte comme download-file et convient pour être figé dans un client ou un lecteur tiers.

5) Écoute pendant la génération

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 à true signifie qu'il s'agit d'une adresse d'écoute temporaire pour un morceau en cours de génération ; passez à l'adresse définitive une fois le morceau terminé. Si un morceau échoue, cet élément porte un champ error et les autres sont renvoyés normalement.

Remarques

• Tous les points d'accès ne renvoient que des adresses de médias hébergés par la plateforme ; ils ne renvoient jamais la source chiffrée de Suno ni une adresse signée temporaire.
• Les adresses ne sont pas permanentes : copiez les fichiers vous-même pour les conserver sur le long terme ; utilisez download-file quand vous avez besoin du fichier d'origine sur disque.
• Le MIDI d'un stem exige que la séparation de ce stem soit terminée, sinon une erreur est renvoyée.