API voor songteksten met tijdstempels

Bijgewerkt op 2026-09-18 · Suno-API-team

Beschrijving van het endpoint

Songteksten met tijdstempels halen tijdstempels op woordniveau van een nummer op, voor gesynchroniseerde weergave van de tekst.

Endpoint: POST /api/lyrics/timeline

Facturering: Gratis (alleen-lezen opvraag; er wordt niets afgerekend en er wordt geen generatieopdracht aangemaakt).

Retourformaat: de tijdlijnarray wordt direct teruggegeven — er is geen data- / success-omhulsel; na het parsen is het gewoon een array.

Verzoekparameters

Headers

Body-parameters

Voorbeeldverzoek

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

Antwoord

Hieronder staat een echte productie-respons voor een nummer van 189,6 seconde in suno-v6 (die aanroep had 69 segmenten; hier zijn alleen de eerste en laatste bewaard):

[
  {
    "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
  }
]

Veldreferentie

Waar u op moet letten

1. Zoek geen omhulsel. Het antwoord is de array zelf, niet {"data": ...}, en er is ook geen success-veld.
2. Aan het begin kan een segment ontbreken. Bij een nummer met een pure intro liet de meting het eerste segment pas op seconde 15 zien, en start_s begint niet gegarandeerd bij 0; voor karaoke behandelt u de opening zelf.
3. Ook instrumentale en structuurmarkeringen worden teruggegeven, in vormen als [Intro], [Verse 1], Instrumental: soft arpeggiating piano, … en [End], eveneens met tijden per woord. Filter deze segmenten vóór het bouwen van ondertitels weg op een leidende [ of op Instrumental; anders verschijnen arrangementbeschrijvingen als songtekst.
4. Het is per woord, niet per regel. Dezelfde regel tekst wordt vaak in meerdere segmenten opgesplitst en moet met \n tot regels worden samengevoegd; de tijd van een regel is de start_s van het eerste segment.
5. Het aantal segmenten hangt van het nummer af; ga niet uit van een vast aantal (gemeten: een nummer van 189,6 seconde had 69 segmenten en een antwoordbody van ongeveer 6,5 KB).

Een .lrc-bestand genereren

Dit endpoint geeft alleen tijdlijngegevens terug; het geeft geen bestand direct terug. Hebt u .lrc nodig, bouw dan regels uit de teruggegeven start_s in de notatie [mm:ss.cc] (het veld word bevat eigen regeleinden — splits per regel en sla lege regels over). Zie voor een voorbeeld "Tijdstempel-songteksten (.lrc) ophalen" in de API voor het downloaden en beluisteren van nummer-media.

Hieronder staat een volledige versie met filtering van instrumentale en structuurmarkeringen (één segment per regel, handig om eerst de vorm van de data te controleren):

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)

Compatibiliteitsopmerkingen

De eerdere documentatie gebruikte een voorbeeld met het omhulobject { success, song_id, lyrics: [...] }. De huidige documentatie gaat uit van de direct teruggegeven tijdlijnarray.