API de paroles horodatées

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

Description du point d'accès

Les paroles horodatées récupèrent les horodatages au niveau du mot d'un morceau, pour un affichage synchronisé des paroles.

Point d'accès : POST /api/lyrics/timeline

Facturation : Gratuit (requête en lecture seule ; rien n'est facturé et aucune tâche de génération n'est créée).

Format de retour : le tableau de la timeline est renvoyé directement — il n'y a pas d'enveloppe data / success ; une fois analysé, c'est simplement un tableau.

Paramètres de la requête

Headers

Paramètres du corps

Exemple de requête

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": "clip_id"
  }'

Réponse

Ci-dessous une réponse réelle de production pour un morceau de 189,6 secondes en suno-v6 (cet appel comptait 69 segments ; seuls les premiers et les derniers sont conservés ici) :

[
  {
    "word": "[Intro]\n\n\n[",
    "start_s": 15,
    "end_s": 15.04277,
    "success": true,
    "p_align": 0.99
  },
  {
    "word": "Instrumental: ",
    "start_s": 15.04704,
    "end_s": 15.10264,
    "success": true,
    "p_align": 0.99
  },
  {
    "word": "End]\n\n\n",
    "start_s": 189.16974,
    "end_s": 189.654,
    "success": true,
    "p_align": 0.99
  }
]

Référence des champs

Points d'attention

1. Ne cherchez pas d'enveloppe. La réponse est le tableau lui-même, pas {"data": ...}, et il n'y a pas non plus de champ success.
2. Il peut ne pas y avoir de segment au début. Sur un morceau à introduction pure, la mesure montre le premier segment seulement à la 15e seconde, et start_s ne commence pas forcément à 0 ; pour du karaoké, gérez vous-même le blanc initial.
3. Les marqueurs instrumentaux et de structure sont aussi renvoyés, sous des formes comme [Intro], [Verse 1], Instrumental: soft arpeggiating piano, … et [End], également avec un minutage mot par mot. Avant de construire des sous-titres de paroles, filtrez ces segments par le [ initial ou par Instrumental ; sinon les descriptions d'arrangement s'afficheront comme des paroles.
4. C'est mot à mot, pas ligne à ligne. La même ligne de paroles est souvent découpée en plusieurs segments et doit être regroupée en lignes par \n ; l'heure d'une ligne est le start_s de son premier segment.
5. Le nombre de segments dépend du morceau ; ne présumez pas d'un nombre fixe (mesuré : un morceau de 189,6 secondes comptait 69 segments et un corps de réponse d'environ 6,5 Ko).

Générer un fichier .lrc

Ce point d'accès ne renvoie que les données de la timeline ; il ne renvoie pas de fichier directement. Si vous avez besoin d'un .lrc, construisez les lignes à partir du start_s renvoyé au format [mm:ss.cc] (le champ word contient ses propres retours à la ligne : découpez par ligne et ignorez les lignes vides). Pour un exemple, voir « Comment obtenir les paroles horodatées (.lrc) » dans l'API de téléchargement et d'écoute des médias de morceaux.

Ci-dessous une version complète avec filtrage des marqueurs instrumentaux et de structure (un segment par ligne, utile pour vérifier d'abord la forme des données) :

import re

SKIP = re.compile(r"^\[.*\]$|^Instrumental:")

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

Remarques de compatibilité

La documentation précédente utilisait un exemple avec l'objet enveloppe { success, song_id, lyrics: [...] }. La documentation actuelle retient le tableau de la timeline renvoyé directement.