API lời bài hát có mốc thời gian

Cập nhật 2026-09-18 · nhóm Suno-API

Mô tả endpoint

Lời bài hát có mốc thời gian lấy mốc thời gian ở cấp độ từng từ của bài hát, để hiển thị lời đồng bộ.

Endpoint: POST /api/lyrics/timeline

Tính phí: Miễn phí (truy vấn chỉ đọc; không tính phí và không tạo tác vụ tạo nhạc).

Định dạng trả về: mảng dòng thời gian được trả về trực tiếp — không có lớp bọc data / success; sau khi phân tích chỉ là một mảng.

Tham số yêu cầu

Headers

Tham số body

Ví dụ yêu cầu

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

Phản hồi

Dưới đây là phản hồi thật từ môi trường sản xuất cho một bài hát 189,6 giây ở suno-v6 (lần gọi đó có 69 đoạn; ở đây chỉ giữ vài đoạn đầu và cuối):

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

Tham chiếu trường

Những điểm cần lưu ý

1. Đừng đi tìm lớp bọc. Phản hồi chính là mảng, không phải {"data": ...}, và cũng không có trường success.
2. Có thể không có đoạn nào ở đầu. Với bài hát chỉ có phần dạo, đo đạc cho thấy đoạn đầu tiên chỉ xuất hiện ở giây 15, và start_s không đảm bảo bắt đầu từ 0; nếu làm karaoke, hãy tự xử lý khoảng trống đầu bài.
3. Các dấu hiệu nhạc cụ và cấu trúc cũng được trả về, dạng [Intro], [Verse 1], Instrumental: soft arpeggiating piano, …, [End], và cũng có mốc thời gian từng từ. Trước khi làm phụ đề lời, hãy lọc các đoạn này theo [ ở đầu hoặc theo Instrumental, nếu không phần mô tả phối khí sẽ hiện như lời bài hát.
4. Là theo từng từ, không phải từng dòng. Cùng một dòng lời thường bị chia thành nhiều đoạn và cần gộp thành dòng theo \n; thời gian của một dòng là start_s của đoạn đầu tiên trong dòng đó.
5. Số đoạn phụ thuộc vào bài hát; đừng giả định số đoạn cố định (đo đạc: bài hát 189,6 giây có 69 đoạn, phần thân phản hồi khoảng 6,5 KB).

Tạo tệp .lrc

Endpoint này chỉ trả về dữ liệu dòng thời gian, không trả về tệp trực tiếp. Khi cần .lrc, hãy ghép dòng từ start_s nhận được theo định dạng [mm:ss.cc] (trường word có sẵn ký tự xuống dòng — hãy tách theo dòng và bỏ qua dòng trống). Ví dụ xem mục "Cách lấy lời có mốc thời gian (.lrc)" trong API tải và nghe thử media của bài hát.

Dưới đây là bản đầy đủ có lọc dấu hiệu nhạc cụ/cấu trúc (mỗi đoạn một dòng, phù hợp để kiểm tra hình dạng dữ liệu trước):

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)

Ghi chú tương thích

Tài liệu trước đây dùng ví dụ với đối tượng bọc { success, song_id, lyrics: [...] }. Tài liệu hiện tại lấy mảng dòng thời gian được trả về trực tiếp làm chuẩn.