Timestamped lyrics API

Updated 2026-09-18 · Suno-API team

Endpoint description

Timestamped lyrics retrieves word-level timestamps for a song, for synchronised lyric display.

Endpoint: POST /api/lyrics/timeline

Billing: Free (read-only query; nothing is charged and no generation task is created).

Return format: the timeline array is returned directly — there is no data / success wrapper; once parsed it is simply an array.

Request parameters

Headers

Body parameters

Request example

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

Response

Below is a real production response for a 189.6-second suno-v6 song (that call had 69 segments; only the first and last few are kept here):

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

Field reference

Things to watch out for

1. Do not look for a wrapper. The response is the array itself, not {"data": ...}, and it has no success field.
2. There may be no segment at the start. For a song with a pure intro, measurement showed the first segment appearing only at second 15, and start_s is not guaranteed to start from 0; for karaoke, handle the leading gap yourself.
3. Instrumental and structure markers are returned too, in forms such as [Intro], [Verse 1], Instrumental: soft arpeggiating piano, … and [End], also with word-level timing. Before building lyric subtitles, filter these segments out by a leading [ or by Instrumental, otherwise arrangement descriptions will be shown as lyrics.
4. It is per word, not per line. The same lyric line is often split into several segments and must be merged into lines by \n; a line's time is the start_s of its first segment.
5. The number of segments depends on the song; do not assume a fixed count (measured: a 189.6-second song had 69 segments and a response body of about 6.5 KB).

Generating a .lrc file

This endpoint only returns timeline data; it does not return a file directly. When you need .lrc, build lines from the returned start_s in [mm:ss.cc] format (the word field carries its own line breaks — split by line and skip empty lines). For an example see "How to get timestamped lyrics (.lrc)" in the song media download and preview API.

Below is a complete version with instrumental/structure marker filtering (one segment per line, good for verifying the data shape first):

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)

Compatibility notes

Older documentation used a { success, song_id, lyrics: [...] } wrapper example. The current documentation takes the directly returned timeline array as authoritative.