API tải và nghe thử media của bài hát

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

Mô tả endpoint

Nhóm endpoint này tách "lấy địa chỉ media" khỏi "tải tệp thật sự":

• Muốn lấy một địa chỉ có thể phát hoặc tải trực tiếp (ví dụ đưa vào trình phát của bạn hoặc sao chép sang kho đối tượng): dùng POST /api/music/download-url, hoặc GET /api/music/download vốn đã có trong phản hồi.
• Muốn trình duyệt lưu tệp xuống đĩa: dùng POST /api/music/download-file (một tệp) hoặc POST /api/music/download-all (đóng gói).
• Bài hát còn đang tạo và muốn nghe trước: dùng POST /api/music/generation-stream-url.

Tính phí: Tất cả miễn phí. Tải và nghe thử chỉ đọc media mà nền tảng đã lưu trữ, không gọi Suno và không tính phí.

Model được khuyến nghị: suno-v6. Có thể dùng suno-v6, suno-v6-wild hoặc suno-v6-mini.

Xác thực

Các loại media được hỗ trợ (kind)

1) Lấy địa chỉ media

curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "song_id",
    "kind": "song",
    "url": "https://media.suno-api.io/assets/song_id-mp3.mp3",
    "nav_url": "https://media.suno-api.io/assets/song_id-mp3.mp3?...&response-content-disposition=attachment..."
  }
}

url dùng để phát hoặc tự sao chép lưu trữ; nav_url mang Content-Disposition: attachment, phù hợp để dán thẳng vào thanh địa chỉ trình duyệt để tải về (dùng khi một số trình duyệt di động không hỗ trợ tải bằng blob).

⚠️ Thời hạn của địa chỉ: 7 ngày — hãy chuyển lưu kịp thời

url / nav_url trỏ tới kho đối tượng của nền tảng và mặc định hết hiệu lực sau 7 ngày (tệp bị thu hồi và địa chỉ cũ trả về 404). Hãy chuyển chúng vào kho của bạn trong 7 ngày đó.

Sau khi hết hạn không cần tạo lại bài hát: gọi lại POST /api/music/download-url (hoặc truyền refresh: true) để nhận địa chỉ mới hợp lệ cho bài hát đó. Nhóm endpoint này miễn phí và không phát sinh thêm phí.

2) Tải trực tiếp một tệp

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}' \
  -o song.mp3

Phần thân phản hồi là luồng tệp (không phải JSON) và Content-Disposition đã có sẵn tên tệp. Lời bài hát và lời có mốc thời gian chỉ lấy được bằng endpoint này (download-url chỉ trả địa chỉ media, không trả lời). Tệp .lrc hiện chỉ hỗ trợ một số bài hát; nếu trả về success:false, hãy tự tạo .lrc bằng API lời bài hát có mốc thời gian theo mục tiếp theo, đừng thử lại.

Cách lấy lời có mốc thời gian (.lrc)

Nên làm hai bước, áp dụng cho mọi bài hát:

Bước 1: lấy dòng thời gian theo từng từ (miễn phí)

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

Kết quả chính là một mảng (không có lớp bọc data); mỗi phần tử có dạng {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word đã chứa ký tự xuống dòng nên có thể tách theo dòng; về ý nghĩa các trường, việc lọc đoạn nhạc không lời và các lưu ý khác, xem "Trường dữ liệu" và "Lưu ý khi dùng" của API lời bài hát có mốc thời gian.

Bước 2: tự ghép .lrc từ start_s (định dạng thời gian [mm:ss.cc])

def to_lrc(segments):
    lines = []
    for seg in segments:
        text = seg["word"].strip()
        if not text:
            continue
        start = max(0.0, float(seg["start_s"]))
        cs = int(start * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

GET /api/music/download?song_id=<id>&kind=lrc cũng tải trực tiếp tệp .lrc do máy chủ tạo, nhưng hiện chỉ một số bài hát được hỗ trợ: nếu trả về success:false, hãy tự tạo theo cách trên — không cần thử lại và không ảnh hưởng đến tính phí.

3) Tải theo gói

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}' \
  -o songs.zip

Dùng song_id (một bài) hoặc song_ids (hàng loạt, tối đa 50 mục). Phần thân phản hồi là luồng ZIP.

4) Địa chỉ tải ổn định

GET /api/music/download?song_id=<id>&kind=<kind> là cổng tải được cung cấp trực tiếp trong phản hồi về bài hát. Nó nhận cả khóa API lẫn trạng thái đăng nhập, hoạt động tương đương download-file và phù hợp để gắn cố định vào ứng dụng khách hoặc trình phát của bên thứ ba.

5) Nghe thử trong khi tạo

curl -X POST https://www.suno-api.io/api/music/generation-stream-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}'

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "song_id": "song_id_1",
        "url": "https://media.suno-api.io/assets/song_id_1-mp3.mp3",
        "expires_at": 0,
        "content_type": "audio/mpeg",
        "playable_until_completed": false,
        "mode": "mp3",
        "ranges": true
      }
    ]
  }
}

playable_until_completed bằng true nghĩa là địa chỉ nghe thử tạm thời của bài hát đang tạo; khi bài hát xong hãy chuyển sang địa chỉ chính thức. Nếu một bài thất bại, mục đó sẽ có trường error, các bài còn lại vẫn trả về bình thường.

Lưu ý

• Mọi endpoint chỉ trả về địa chỉ media do nền tảng lưu trữ; không bao giờ trả về nguồn mã hóa của Suno hay địa chỉ ký tạm thời.
• Địa chỉ không vĩnh viễn: hãy tự chuyển lưu nếu cần giữ lâu dài; khi cần tệp gốc trên đĩa thì dùng download-file.
• MIDI của một stem đòi hỏi stem đó đã tách xong, nếu không sẽ trả về lỗi.