API lirik bertimestamp

Dikemas kini 2026-09-18 · pasukan Suno-API

Penerangan endpoint

Lirik bertimestamp mengambil cap masa pada peringkat perkataan bagi sebuah lagu, untuk memaparkan lirik secara segerak.

Endpoint: POST /api/lyrics/timeline

Pengebilan: Percuma (pertanyaan baca sahaja; tiada caj dikenakan dan tiada tugasan penjanaan dicipta).

Format pemulangan: tatasusunan garis masa dipulangkan terus — tiada pembalut data / success; selepas dihurai ia hanyalah tatasusunan.

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 ialah respons sebenar daripada produksi bagi lagu berdurasi 189.6 saat dalam suno-v6 (panggilan itu mempunyai 69 segmen; di sini hanya bahagian awal dan akhir disimpan):

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

Rujukan medan

Perkara yang perlu diberi perhatian

1. Jangan cari pembalut. Responsnya ialah tatasusunan itu sendiri, bukan {"data": ...}, dan tiada medan success.
2. Mungkin tiada segmen di awal. Bagi lagu yang hanya ada pengenalan, ukuran menunjukkan segmen pertama hanya muncul pada saat ke-15, dan start_s tidak dijamin bermula dari 0; untuk karaoke, uruskan sendiri ruang kosong di awal.
3. Penanda instrumental dan struktur juga dipulangkan, dalam bentuk seperti [Intro], [Verse 1], Instrumental: soft arpeggiating piano, … dan [End], juga dengan masa perkataan demi perkataan. Sebelum membina sari kata lirik, tapis segmen ini berdasarkan [ di awal atau perkataan Instrumental; jika tidak, penerangan susunan muzik akan dipaparkan sebagai lirik.
4. Ia per perkataan, bukan per baris. Baris lirik yang sama sering dipecahkan kepada beberapa segmen dan perlu digabungkan menjadi baris mengikut \n; masa sesuatu baris ialah start_s segmen pertamanya.
5. Bilangan segmen bergantung pada lagu; jangan andaikan bilangan tetap (ukuran: lagu 189.6 saat mempunyai 69 segmen dan badan respons sekitar 6.5 KB).

Menjana fail .lrc

Endpoint ini hanya memulangkan data garis masa; ia tidak memulangkan fail secara terus. Jika perlu .lrc, bina baris daripada start_s yang dipulangkan dalam format [mm:ss.cc] (medan word membawa pemisah baris sendiri — pecahkan mengikut baris dan langkau baris kosong). Untuk contoh, lihat "Cara mendapatkan lirik bertimestamp (.lrc)" dalam API muat turun dan pratonton media lagu.

Di bawah ialah versi penuh dengan penapisan penanda instrumental/struktur (satu segmen satu baris, sesuai untuk memeriksa bentuk data dahulu):

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)

Nota keserasian

Dokumentasi terdahulu menggunakan contoh objek pembalut { success, song_id, lyrics: [...] }. Dokumentasi semasa mengambil tatasusunan garis masa yang dipulangkan terus sebagai rujukan.