API lirik bertimestamp

Diperbarui 2026-09-18 · tim Suno-API

Deskripsi endpoint

Lirik bertimestamp mengambil stempel waktu tingkat kata dari sebuah lagu, untuk menampilkan lirik secara sinkron.

Endpoint: POST /api/lyrics/timeline

Biaya: Gratis (kueri hanya-baca; tidak ada biaya dan tidak ada tugas pembuatan yang dibuat).

Format kembalian: array timeline dikembalikan langsung — tidak ada pembungkus data / success; setelah di-parse ia hanya sebuah array.

Parameter permintaan

Headers

Parameter body

Contoh permintaan

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

Respons

Di bawah ini adalah respons asli dari produksi untuk lagu berdurasi 189,6 detik dengan suno-v6 (panggilan itu punya 69 segmen; di sini hanya disimpan bagian awal dan akhir):

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

Referensi field

Hal yang perlu diperhatikan

1. Jangan mencari pembungkus. Responsnya adalah array itu sendiri, bukan {"data": ...}, dan tidak ada field success.
2. Bisa tidak ada segmen di awal. Untuk lagu dengan intro murni, pengukuran menunjukkan segmen pertama baru muncul di detik ke-15, dan start_s tidak dijamin mulai dari 0; untuk karaoke, tangani sendiri celah di awal.
3. Penanda instrumental dan struktur juga dikembalikan, dalam bentuk seperti [Intro], [Verse 1], Instrumental: soft arpeggiating piano, … dan [End], juga dengan waktu per kata. Sebelum membuat subtitle lirik, saring segmen ini berdasarkan [ di awal atau kata Instrumental; jika tidak, deskripsi aransemen akan tampil sebagai lirik.
4. Ini per kata, bukan per baris. Baris lirik yang sama sering dipecah menjadi beberapa segmen dan harus digabung menjadi baris dengan \n; waktu sebuah baris adalah start_s segmen pertamanya.
5. Jumlah segmen bergantung pada lagunya; jangan mengasumsikan jumlah tetap (pengukuran: lagu 189,6 detik punya 69 segmen dan isi respons sekitar 6,5 KB).

Membuat berkas .lrc

Endpoint ini hanya mengembalikan data timeline; ia tidak mengembalikan berkas secara langsung. Jika perlu .lrc, susun baris dari start_s yang dikembalikan dengan format [mm:ss.cc] (field word membawa baris baru sendiri — pisahkan per baris dan lewati baris kosong). Untuk contohnya lihat "Cara mengambil lirik bertimestamp (.lrc)" di API unduh dan pratinjau media lagu.

Di bawah ini versi lengkap dengan penyaringan penanda instrumental/struktur (satu segmen per baris, cocok untuk memeriksa bentuk datanya lebih dulu):

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)

Catatan kompatibilitas

Dokumentasi sebelumnya memakai contoh objek pembungkus { success, song_id, lyrics: [...] }. Dokumentasi terkini mengacu pada array timeline yang dikembalikan langsung.