API hiệu chỉnh mốc thời gian lời bài hát

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

Đây không phải nhận dạng giọng nói. Văn bản luôn dùng nguyên văn lời bạn đưa; chúng tôi chỉ đặt từng ký tự vào đúng thời điểm — nên không bao giờ có chuyện "nghe nhầm ký tự khiến lời bị lệch".

Mô tả endpoint

Căn khớp lời có sẵn với âm thanh và trả về mốc thời gian theo dòng và theo ký tự, phục vụ tô sáng từng ký tự kiểu karaoke, lời chạy và tạo phụ đề.

Endpoint: POST /api/music/lyrics-align

Xác thực: xem Xác thực; tiêu đề là Authorization: Bearer YOUR_API_KEY

Tính phí: tính theo lần gọi (hiện mặc định 0,1 ¥ mỗi lần); nếu bài hát thuộc nền tảng mà bạn tích tách giọng hát, sẽ tính thêm một lần theo giá "tách giọng hát/nhạc đệm" của nền tảng. Số tiền thực trừ tuân theo cấu hình giá trong phần quản trị.

Thời gian trung bình: 5–15 giây (tùy độ dài âm thanh và việc có phải tách giọng tại chỗ hay không)

Vì sao cần hiệu chỉnh: mốc thời gian phía tạo nhạc không phải lúc nào cũng chính xác

API lời bài hát có mốc thời gian trả về trực tiếp mốc thời gian theo từng từ của phía tạo nhạc, và chúng có sai số:

• đoạn lặp, hòa âm dày, rap và nốt dài thường lệch tổng thể hoặc lệch vài ký tự;
• một số bài thiếu một đoạn ở đầu (ví dụ đoạn dạo thuần nhạc, mảnh đầu tiên chỉ bắt đầu từ giây thứ mười mấy);
• vài dòng khó neo vào một mốc thời gian rõ ràng.

Hiệu chỉnh làm lại việc căn thời gian dựa trên lời do chính bạn cung cấp: chỉ sửa thời gian, không đổi văn bản, phù hợp với các trường hợp cần "khớp chuẩn" (tô sáng từng ký tự kiểu KTV, phụ đề theo ký tự, chấm điểm hát theo).

Cách làm được khuyến nghị (ba bước, hiệu quả nhất)

1. Trích giọng hát thuần trước (tách giọng hát/nhạc đệm) và chỉ căn trên track giọng hát — nhạc đệm và hòa âm không còn gây nhiễu. Căn cứ đo được: khi so sánh từng dòng giữa "bản mix đầy đủ và track giọng hát" của cùng một bài, 5 trong 28 dòng lệch hơn 0,25 giây (nhiều nhất 2,64 giây); hai động cơ độc lập lệch trung bình 0,239 giây trên track giọng hát và 0,508 giây trên bản mix đầy đủ — độ nhất quán gần như chênh gấp đôi. Vì vậy với tô sáng từng ký tự (KTV/phụ đề) nên bật. (Mức cải thiện cụ thể đang được đo lại bằng động cơ mới.)
2. Cung cấp lời đầy đủ: cả bài, theo dòng, khớp một-một với âm thanh. Thiếu một câu hay một đoạn sẽ làm lệch toàn bộ các dòng sau; đừng đưa mốc thời gian như [00:23.82] vào lời (có cũng sẽ tự bỏ qua).
3. Với bài hát của nền tảng chỉ cần tích vocal_separate: true, chúng tôi làm "tách + căn" trong một bước.

Ba cách dùng

Quan hệ giữa các tham số (chỗ dễ sai nhất, hãy đọc kỹ)

• Gửi song_id → đi đường bài hát nền tảng: đừng gửi thêm lyrics / audio_url / audio_object_key;
• Gửi audio_url hoặc audio_object_key → đi đường bài hát ngoài: chỉ một trong hai, và đừng gửi song_id;
• vocal_separate chỉ có hiệu lực với bài hát nền tảng; gửi cho bài hát ngoài sẽ bị từ chối (âm thanh không ở phía chúng tôi, không tách được).

Mới: tải tệp cục bộ trực tiếp (âm thanh không đi qua máy chủ của chúng tôi)

Dùng khi âm thanh ở trên máy bạn và bạn không muốn đưa lên kho công khai của mình trước. Hai bước:

1. Gọi POST /api/music/lyrics-align/upload-ticket với file_name / file_size / content_type, nhận put_url (URL đã ký, không chứa thông tin xác thực dài hạn) và object_key;
2. PUT tệp lên put_url, phải mang nguyên content_type trong phản hồi (nó tham gia chữ ký; đổi một ký tự là 403);
3. Khi gửi yêu cầu căn, truyền audio_object_key thay vì audio_url.

Thông tin xác thực dùng một lần: khi việc căn xong (thành công hay thất bại) máy chủ sẽ xoá đối tượng này, dùng lại cùng key sẽ báo lỗi.

Mới: lời đã có thể không gửi

Trước đây bài hát ngoài bắt buộc phải có lời. Nay có thể bỏ qua: máy chủ chạy một lần nhận dạng và dùng văn bản nhận dạng được làm lời.

Cái giá phải nói rõ: văn bản khi đó lấy theo kết quả nhận dạng, vài ký tự có thể sai. Những phản hồi này được ghi rõ lyrics_source: "asr", confidence: "low" và trong warnings[] có {"code":"no_reference_lyrics"}.

Muốn tô sáng từng ký tự / KTV thì nhất định phải cung cấp nguyên văn lời.

Tham số yêu cầu

Headers

Tham số body

Giới hạn

Ví dụ yêu cầu

Bài hát ngoài (lời + địa chỉ âm thanh)

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": "Bước qua phố lạnh\nGío đêm khẽ chạm mắt tôi\nThời gian trôi như nước",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

Bài hát nền tảng (không tách)

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

Bài hát nền tảng + tách giọng hát (khuyến nghị cho 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}'

Phản hồi

Phản hồi thành công

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "Bước qua phố lạnh",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "B", "start": 21.66, "end": 21.74, "word": true},
        {"char": "ư", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

Giải thích các trường

Dùng coverage thế nào (ba mức)

Trạng thái và thời gian

Giới hạn một lần chạy trên máy chủ là 8 phút; nên đặt timeout phía client từ 120 giây trở lên.

Phản hồi lỗi

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

Nguyên tắc: không có kết quả cuối cùng thì hoàn tiền toàn bộ. Chỉ tính phí khi mốc thời gian từng ký tự thực sự được trả về, và việc hoàn tiền tự động, không cần yêu cầu.

Tính phí

Quan hệ kết hợp:

thực trả = giá cơ bản + (không cung cấp lời ? phụ phí chép lời : 0) + (tích tách ? giá tách : 0)

Phí tách giọng hát chỉ thu một lần: nếu bạn đã tách và có sẵn track giọng hát thì endpoint này thu; nếu phải tách tại chỗ thì bước tách thu.

Ví dụ đầy đủ (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("chất lượng căn khớp coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # karaoke từng ký tự: mỗi ký tự trong line["chars"] có start / end riêng

Câu hỏi thường gặp

H: Kết quả là theo ký tự hay theo dòng? Đ: Cả hai. lines[].start là theo dòng, lines[].chars[].start / end là theo ký tự; trình phát cần cái nào thì lấy cái đó.

H: Vì sao văn bản trả về giống hệt cái tôi gửi? Đ: Thiết kế là vậy. Chúng tôi không nhận dạng rồi viết lại, chỉ căn thời gian, nên lời không bao giờ bị "sửa thành lỗi chính tả".

H: coverage cao mà nghe vẫn hơi lệch? Đ: Sai số từng ký tự thường ở mức vài chục mili giây; nếu cả bài lệch một lượng cố định thì nhiều khả năng đầu âm thanh có một đoạn im lặng — cắt bỏ rồi thử lại.

H: Vì sao lúc trước tách dùng được, một lúc sau lại báo "track giọng hát không khả dụng"? Đ: Kết quả tách là địa chỉ tạm thời có hiệu lực ngắn (đo được: hết hiệu lực sau khoảng nửa giờ). Khi đó endpoint sẽ tự thử tách lại; nếu vẫn thất bại sẽ hoàn tiền toàn bộ. Nên cách dùng "tách trước, hiệu chỉnh sau" không đáng tin — hãy làm liền trong cùng một luồng.

H: Bài hát nền tảng có cần tôi tự tách trước không? Đ: Không. Khi tích vocal_separate: true chúng tôi kiểm tra bài đó đã có track giọng hát chưa; không có track dùng được thì báo lỗi và hoàn tiền, chứ không dùng bản gốc để cho qua.

H: Có làm theo lô được không? Đ: Một lần gọi một bài. Theo lô thì tự lặp; mỗi lần gọi đều tính phí bình thường, nên lưu kết quả vào bộ nhớ đệm cục bộ.

H: Kết quả có được lưu không? Đ: Endpoint này không lưu trữ, hãy tự lưu giá trị trả về (mốc thời gian theo dòng và theo ký tự đều có trong phản hồi).