Lyrics timestamp alignment API

Updated 2026-09-18 · Suno-API team

This is not speech recognition. The text always uses the lyrics you supply verbatim; we only place each character at the correct time — so you never get "misheard characters making the lyrics mismatch".

Endpoint description

It aligns existing lyrics with audio and outputs line-level + character-level timestamps, for karaoke character highlighting, scrolling lyrics and subtitle generation.

Endpoint: POST /api/music/lyrics-align

Authentication: see Authentication; the request header is Authorization: Bearer YOUR_API_KEY

Billing: charged per call (currently 0.1 ¥ per call by default); for a platform song with vocal separation selected, the platform's "vocal/backing separation" price is charged once more. The amount actually charged follows the current back-office price configuration.

Average time: 5–15 seconds (depending on audio length and whether vocal separation has to be done on the spot)

Why calibration is needed: generated timestamps are not always accurate

The timestamped lyrics API returns the generation side's per-word timestamps directly, and they carry inaccuracies:

• reprises, heavy harmonies, rap and long held notes often drift overall or shift individual characters;
• some songs are missing a stretch at the start (for example a pure intro, with the first segment only starting in the teens);
• some lyric lines are hard to pin to a clear time anchor.

Lyrics timestamp alignment re-does the time alignment on the lyrics you supply yourself: only the timing is corrected, never the text, which suits cases that care about "does it line up" (KTV character highlighting, per-character subtitles, sing-along scoring).

Recommended approach (three steps, best results)

1. Extract the vocal first (vocal/backing separation) and align only the vocal track — backing and harmonies stop interfering. Measured basis: in a line-by-line comparison of "full mix vs vocal track" for the same song, 5 of 28 lines differed by more than 0.25 s (the largest by 2.64 s); two independent engines differed on average by 0.239 s on the vocal track and 0.508 s on the full mix — nearly half the agreement. So for character highlighting (KTV/subtitles) it is recommended to switch it on. (The exact gain is being re-measured with the new engine.)
2. Provide the complete lyrics: the whole song, line by line, matching the audio one-to-one. A missing sentence or section shifts all the following lines; do not include timestamps such as [00:23.82] in the lyrics (they are ignored automatically).
3. For a platform song you can simply tick vocal_separate: true, and we do "separation + alignment" in one step.

Three ways to use it

How the parameters relate (the easiest thing to get wrong — read carefully)

• Sending song_id → platform song route: do not send lyrics / audio_url / audio_object_key as well;
• Sending audio_url or audio_object_key → external song route: send only one of the two, and do not send song_id;
• vocal_separate only works for platform songs; sending it for an external song is rejected (the audio is not on our side, so it cannot be separated).

New: direct local upload (the audio never passes through our servers)

Use this when the audio is on your machine and you would rather not upload it to your own public storage first. Two steps:

1. POST /api/music/lyrics-align/upload-ticket with file_name / file_size / content_type and get back a put_url (a signed URL with no long-lived credentials) and an object_key;
2. PUT the file to put_url, carrying the content_type from the response exactly as given (it takes part in the signature; one changed character means 403);
3. When submitting the alignment, send audio_object_key instead of audio_url.

The credential is single-use: once the alignment finishes (success or failure) the server deletes the object, and reusing the same key reports an error.

New: the lyrics are now optional

External songs used to require lyrics. Now you can omit them — the server runs recognition once and uses the recognised text as the lyrics.

The trade-off must be stated clearly: the text then follows the recognition result, so individual characters may be wrong. Such responses are clearly marked with lyrics_source: "asr", confidence: "low" and, in warnings[], {"code":"no_reference_lyrics"}.

For character-level highlighting / KTV, always supply the original lyrics.

Request parameters

Headers

Body parameters

Limits

Request examples

External song (lyrics + audio address)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lyrics": "Wandering the chilly streets\nNight wind brushes my eyes\nTime flows on like water",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

Platform song (no separation)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "17e52af7-b5df-4877-a98a-dce94e0e6aa2"}'

Platform song + vocal separation (recommended for karaoke)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "17e52af7-b5df-4877-a98a-dce94e0e6aa2", "vocal_separate": true}'

Response

Success response

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "Wandering the chilly streets",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "W", "start": 21.66, "end": 21.74, "word": true},
        {"char": "a", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

Field reference

How to use coverage (three tiers)

Status and timing

The server's single-run limit is 8 minutes; set your client timeout to 120 seconds or more.

Error responses

{
  "success": false,
  "message": "音频超过 6 分钟上限（实际 7.2 分钟）"
}

Principle: no final result means a full refund. The charge applies only when per-character timestamps are actually returned, and refunds are automatic — no request needed.

Billing

The combination:

amount due = base price + (no lyrics supplied ? transcription surcharge : 0) + (separation ticked ? separation price : 0)

The vocal separation fee is charged only once: if you have already separated the song and the vocal track is available directly, this endpoint charges it; if separation has to happen on the spot, the separation step charges it.

Full example (Python)

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://www.suno-api.io"

def align_lyrics(song_id=None, lyrics=None, audio_url=None, vocal_separate=False):
    payload = {}
    if song_id:
        payload["song_id"] = song_id
        payload["vocal_separate"] = vocal_separate
    else:
        payload["lyrics"] = lyrics
        payload["audio_url"] = audio_url

    r = requests.post(
        f"{BASE}/api/music/lyrics-align",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=600,
    )
    data = r.json()
    if not data.get("success"):
        raise RuntimeError(data.get("message"))
    return data


res = align_lyrics(song_id="17e52af7-b5df-4877-a98a-dce94e0e6aa2", vocal_separate=True)
print("alignment quality coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # per-character karaoke: every character in line["chars"] has its own start / end

FAQ

Q: Is the output per character or per line? A: Both. lines[].start is line-level; lines[].chars[].start / end are per character — the player takes whichever it needs.

Q: Why is the returned text identical to what I sent? A: By design. We do not recognise-and-rewrite; we only align timing, so the lyrics can never be "corrected into typos".

Q: coverage is high but it still sounds slightly off? A: Per-character alignment error is usually in the tens of milliseconds; if the whole song is off by a fixed amount, it is most likely a stretch of silence at the start of the audio, so trim it and try again.

Q: Why did separation work a moment ago, and now it reports "vocal track unavailable"? A: Separation results are short-lived temporary addresses (measured to expire after roughly half an hour). In that case the endpoint tries to separate again automatically; if it still fails you get a full refund. So "separate now, align later" is not reliable — do the two in the same flow.

Q: Do I need to separate a platform song myself first? A: No. With vocal_separate: true we check whether the song already has a vocal track; if there is no usable vocal track it reports an error and refunds rather than fobbing you off with the full mix.

Q: Can I batch them? A: One song per request. For batches, loop; every call is charged normally, so caching results locally is recommended.

Q: Is the result saved? A: This endpoint does not persist anything; save the returned value yourself (both line-level and per-character timestamps are in the response).