API für zeitgestempelte Songtexte

Aktualisiert am 2026-09-18 · Suno-API-Team

Beschreibung des Endpunkts

Zeitgestempelte Songtexte liefern Zeitstempel auf Wortebene für einen Song — für die synchronisierte Anzeige des Textes.

Endpunkt: POST /api/lyrics/timeline

Abrechnung: Kostenlos (reine Leseabfrage; es wird nichts berechnet und kein Generierungsauftrag erzeugt).

Rückgabeformat: Das Timeline-Array wird direkt zurückgegeben — es gibt keine data- / success-Hülle; nach dem Parsen ist es einfach ein Array.

Anfrageparameter

Headers

Body-Parameter

Beispielanfrage

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

Antwort

Unten steht eine echte Produktionsantwort für einen 189,6 Sekunden langen Song in suno-v6 (dieser Aufruf hatte 69 Segmente; hier sind nur die ersten und letzten erhalten):

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

Feldreferenz

Wichtige Hinweise

1. Suchen Sie keine Hülle. Die Antwort ist das Array selbst, nicht {"data": ...}, und es gibt auch kein success-Feld.
2. Am Anfang kann ein Segment fehlen. Bei einem Song mit reinem Intro zeigte die Messung das erste Segment erst bei Sekunde 15, und start_s beginnt nicht garantiert bei 0; für Karaoke behandeln Sie die Lücke am Anfang selbst.
3. Auch Instrumental- und Strukturmarker werden zurückgegeben, in Formen wie [Intro], [Verse 1], Instrumental: soft arpeggiating piano, … und [End], ebenfalls mit Zeitangaben Wort für Wort. Filtern Sie diese Segmente vor dem Bau von Untertiteln über das führende [ oder Instrumental heraus; sonst erscheinen Arrangement-Beschreibungen als Songtext.
4. Es ist wortweise, nicht zeilenweise. Dieselbe Textzeile wird oft in mehrere Segmente zerlegt und muss per \n zu Zeilen zusammengeführt werden; die Zeit einer Zeile ist das start_s ihres ersten Segments.
5. Die Segmentzahl hängt vom Song ab; gehen Sie nicht von einer festen Anzahl aus (gemessen: ein 189,6-Sekunden-Song hatte 69 Segmente und einen Antwort-Body von etwa 6,5 KB).

Eine .lrc-Datei erzeugen

Dieser Endpunkt liefert nur Timeline-Daten; er liefert keine Datei direkt. Wenn Sie .lrc brauchen, bauen Sie die Zeilen aus dem zurückgegebenen start_s im Format [mm:ss.cc] (das Feld word enthält eigene Zeilenumbrüche — nach Zeilen aufteilen und leere Zeilen überspringen). Ein Beispiel steht unter „Wie man zeitgestempelte Songtexte (.lrc) erhält“ in der API zum Herunterladen und Anhören von Song-Medien.

Unten steht eine vollständige Variante mit Filterung der Instrumental- und Strukturmarker (ein Segment pro Zeile, gut geeignet, um zuerst die Datenform zu prüfen):

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)

Kompatibilitätshinweise

Die frühere Dokumentation verwendete ein Beispiel mit dem Hüllobjekt { success, song_id, lyrics: [...] }. Die aktuelle Dokumentation betrachtet das direkt zurückgegebene Timeline-Array als maßgeblich.