API tekstu z znacznikami czasu

Zaktualizowano 2026-09-18 · zespół Suno-API

Opis punktu końcowego

Tekst z znacznikami czasu zwraca znaczniki czasu na poziomie słów dla utworu — do zsynchronizowanego wyświetlania tekstu.

Punkt końcowy: POST /api/lyrics/timeline

Rozliczenie: Bezpłatne (zapytanie tylko do odczytu; nic nie jest pobierane i nie tworzy się zadanie generowania).

Format odpowiedzi: tablica osi czasu jest zwracana bezpośrednio — nie ma zewnętrznej otoczki data / success; po sparsowaniu to po prostu tablica.

Parametry żądania

Headers

Parametry body

Przykład żądania

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

Odpowiedź

Poniżej prawdziwa odpowiedź produkcyjna dla utworu o długości 189,6 sekundy w suno-v6 (to wywołanie miało 69 segmentów; zachowano tu tylko pierwsze i ostatnie):

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

Opis pól

Na co uważać

1. Nie szukaj otoczki. Odpowiedzią jest sama tablica, a nie {"data": ...}, i nie ma w niej pola success.
2. Na początku może nie być segmentu. W utworze z czystym wstępem pomiar pokazał pierwszy segment dopiero w 15. sekundzie, a start_s nie musi zaczynać się od 0; przy karaoke obsłuż początkową lukę samodzielnie.
3. Zwracane są także znaczniki instrumentalne i strukturalne, w postaciach [Intro], [Verse 1], Instrumental: soft arpeggiating piano, … i [End], również z czasami słowo po słowie. Przed budowaniem napisów odfiltruj te segmenty po początkowym [ albo po Instrumental; inaczej opisy aranżacji pojawią się jako tekst utworu.
4. To podział na słowa, nie na linie. Ta sama linia tekstu bywa dzielona na kilka segmentów i trzeba je scalić w linie po \n; czas linii to start_s jej pierwszego segmentu.
5. Liczba segmentów zależy od utworu; nie zakładaj stałej liczby (pomiar: utwór 189,6 sekundy miał 69 segmentów, a treść odpowiedzi około 6,5 KB).

Generowanie pliku .lrc

Ten punkt końcowy zwraca tylko dane osi czasu; nie zwraca pliku bezpośrednio. Jeśli potrzebujesz .lrc, złóż linie z zwróconego start_s w formacie [mm:ss.cc] (pole word zawiera własne znaki nowej linii — podziel po liniach i pomiń puste). Przykład znajdziesz w sekcji „Jak pobrać tekst z znacznikami czasu (.lrc)” w API pobierania i odsłuchu mediów utworów.

Poniżej pełna wersja z filtrowaniem znaczników instrumentalnych i strukturalnych (jeden segment na linię, dobra do sprawdzenia najpierw kształtu danych):

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)

Uwagi o zgodności

Wcześniejsza dokumentacja używała przykładu z obiektem-otoczką { success, song_id, lyrics: [...] }. Obecna dokumentacja przyjmuje jako obowiązującą tablicę osi czasu zwracaną bezpośrednio.