タイムライン歌詞 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 | そのセグメントに対応するテキスト。改行を含みます: 歌詞 1 行が 1 段で、段末に \n、段落の間は \n\n になるため、空白だけの内容も現れます |
start_s |
number | セグメント開始時刻（秒、小数あり） |
end_s |
number | セグメント終了時刻（秒）。最後の段の end_s はほぼ楽曲の長さに等しくなります |
success |
boolean | そのセグメントの整列が成功したかどうか |
p_align |
number | 整列の信頼度。実測では安定して 0.99 |
使用上の注意
- 外側のラッパーを探さないでください。返却は配列そのもので、
{"data": ...}ではなく、successフィールドもありません。 - 冒頭にセグメントがないことがあります。前奏だけの楽曲では、実測で 15 秒目から最初のセグメントが現れ、
start_sが0から始まる保証はありません。カラオケ用途では冒頭の空きをご自身で処理してください。 - 器楽・構造マーカーも返ります。
[Intro]、[Verse 1]、Instrumental: soft arpeggiating piano, …、[End]のような形で、同じく逐語で時間が付きます。歌詞字幕を作る前に、[で始まるものやInstrumentalを除外することをおすすめします。そうしないと編曲の説明を歌詞として表示してしまいます。 - 逐語であって逐行ではありません。同じ 1 行の歌詞が複数のセグメントに分かれることが多く、
\nで行にまとめる必要があります。行の時間はその行の最初のセグメントのstart_sです。 - 段数は楽曲によって異なります。固定段数を前提にしないでください（実測では 189.6 秒の楽曲が 69 段、レスポンスは約 6.5 KB）。
.lrc ファイルの生成
このエンドポイントはタイムラインのデータのみを返し、ファイルは直接返しません。.lrc が必要な場合は、返却された start_s を使って [mm:ss.cc] 形式で行を組み立ててください（word フィールドは改行を含むので行ごとに分割し、空行は飛ばします）。例は楽曲メディアのダウンロードと試聴 APIの「タイムライン歌詞（.lrc）の取得方法」をご覧ください。
以下は器楽・構造マーカーのフィルタ付きの完全な書き方です（1 段 1 行、まずデータ形態を確認するのに向いています）：
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: [...] } のラッパーオブジェクト例が使われていました。現行の新版ドキュメントは、タイムライン配列をそのまま返す形を正とします。