時間軸歌詞 API
介面說明
時間軸歌詞用於取得歌曲逐詞級別的時間戳，可用於歌詞同步顯示。
介面位址: POST /api/lyrics/timeline
計費: 免費（唯讀查詢，不扣費、不產生生成任務）。
返回格式: 直接返回時間軸陣列，沒有 data / success 外層包裝，解析後就是一個陣列。
請求參數
Headers
| 參數名 | 型別 | 必填 | 說明 |
|---|---|---|---|
| Authorization | string | 是 | Bearer YOUR_API_KEY |
| Content-Type | string | 是 | application/json |
請求主體參數
| 參數名 | 型別 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
| model | string | 否 | suno-v6 | 對客模型名：suno-v6、suno-v6-wild 或 suno-v6-mini |
| song_id | string | 是 | - | 歌曲 ID |
請求範例
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"
}'
回應結果
下面是生產環境一首 189.6 秒、suno-v6 歌曲的真實返回（該次共 69 段，這裡只保留首尾幾段）：
[
{
"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
}
]
欄位說明
| 欄位 | 型別 | 說明 |
|---|---|---|
word |
string | 該片段對應的文字，自帶換行：一行歌詞一段、段尾帶 \n，段落之間是 \n\n，因此會出現只含空白的內容 |
start_s |
number | 片段開始時間，單位秒（帶小數） |
end_s |
number | 片段結束時間，單位秒。最後一段的 end_s 基本等於歌曲時長 |
success |
boolean | 該片段是否對齊成功 |
p_align |
number | 對齊信心度，實測穩定在 0.99 |
使用注意
- 不要找外層包裝。返回就是陣列本身，不是
{"data": ...}，也沒有success欄位。 - 開頭可能沒有片段。純前奏的歌曲實測從第 15 秒才出現第一個片段，
start_s不保證從0開始；做卡拉 OK 時請自己處理開頭的空檔。 - 器樂與結構標記也會返回，形如
[Intro]、[Verse 1]、Instrumental: soft arpeggiating piano, …、[End]，並且同樣逐詞給出時間。做歌詞字幕前建議按[開頭或Instrumental過濾掉這些片段，否則會把編曲描述當成歌詞顯示。 - 是逐詞而不是逐行。同一句歌詞常被拆成多個片段，需要按
\n合併成行；一行的時間取該行第一個片段的start_s。 - 段數與歌曲有關，不要假設固定段數（實測 189.6 秒的歌為 69 段，回應體約 6.5 KB）。
產生 .lrc 檔案
本介面只返回時間軸資料，不直接返回檔案。需要 .lrc 時，用返回的 start_s 按
[mm:ss.cc] 格式拼行即可（word 欄位自帶換行，按行拆開，空行跳過）。範例見
歌曲媒體下載與試聽 API 的「時間軸歌詞（.lrc）怎麼取」。
下面是帶器樂/結構標記過濾的完整寫法（一段一行，適合先驗證資料形態）：
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)
相容說明
舊版文件中曾使用 { success, song_id, lyrics: [...] } 包裝物件範例。當前新版文件以直接返回時間軸陣列為準。