API för tidsstämplad låttext

Uppdaterad 2026-09-18 · Suno-API-teamet

Beskrivning av ändpunkten

Tidsstämplad låttext hämtar tidsstämplar på ordnivå för en låt, för synkroniserad visning av texten.

Ändpunkt: POST /api/lyrics/timeline

Fakturering: Kostnadsfritt (endast läsning; inget debiteras och inget genereringsuppdrag skapas).

Returformat: tidslinje-arrayen returneras direkt — det finns ingen data- / success-omslutning; efter parsning är det helt enkelt en array.

Begäransparametrar

Headers

Body-parametrar

Exempelbegäran

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

Svar

Nedan finns ett verkligt produktionssvar för en låt på 189,6 sekunder i suno-v6 (det anropet hade 69 segment; här behålls bara de första och sista):

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

Fältreferens

Saker att se upp med

1. Leta inte efter en omslutning. Svaret är själva arrayen, inte {"data": ...}, och den har inte heller något success-fält.
2. Det kan saknas ett segment i början. För en låt med enbart intro visade mätningen att första segmentet dök upp först vid sekund 15, och start_s börjar inte garanterat på 0; för karaoke får du hantera luckan i början själv.
3. Instrumentala och strukturella markeringar returneras också, i former som [Intro], [Verse 1], Instrumental: soft arpeggiating piano, … och [End], även de med tider ord för ord. Filtrera bort dessa segment via inledande [ eller Instrumental innan du bygger undertexter, annars visas arrangemangsbeskrivningar som låttext.
4. Det är per ord, inte per rad. Samma textrad delas ofta upp i flera segment och måste slås ihop till rader via \n; en rads tid är dess första segments start_s.
5. Antalet segment beror på låten; utgå inte från ett fast antal (mätt: en låt på 189,6 sekunder hade 69 segment och en svarsbody på cirka 6,5 KB).

Skapa en .lrc-fil

Den här ändpunkten returnerar bara tidslinjedata; den returnerar ingen fil direkt. Om du behöver .lrc bygger du rader av den returnerade start_s i formatet [mm:ss.cc] (word-fältet innehåller egna radbrytningar — dela per rad och hoppa över tomma rader). Ett exempel finns under "Så hämtar du tidsstämplad låttext (.lrc)" i API för nedladdning och uppspelning av låtmedia.

Nedan finns en komplett variant med filtrering av instrumentala och strukturella markeringar (ett segment per rad, bra för att först kontrollera datans form):

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)

Kompatibilitetsnoter

Tidigare dokumentation använde ett exempel med omslutningsobjektet { success, song_id, lyrics: [...] }. Den aktuella dokumentationen utgår från tidslinje-arrayen som returneras direkt.