API muat turun dan pratonton media lagu

Dikemas kini 2026-09-18 · pasukan Suno-API

Penerangan endpoint

Kumpulan endpoint ini memisahkan "mendapatkan alamat media" daripada "memuat turun fail sebenar":

• Untuk mendapatkan alamat yang boleh dimainkan atau dimuat turun terus (contohnya untuk dimasukkan ke pemain anda sendiri atau disalin ke storan objek): gunakan POST /api/music/download-url, atau GET /api/music/download yang sudah ada dalam respons.
• Untuk membenarkan pelayar menyimpan fail ke cakera: gunakan POST /api/music/download-file (satu fail) atau POST /api/music/download-all (pakej).
• Jika lagu masih dijana dan anda mahu mendengar dahulu: gunakan POST /api/music/generation-stream-url.

Pengebilan: Semuanya percuma. Muat turun dan pratonton hanya membaca media yang sudah dihoskan platform; ia tidak memanggil Suno dan tidak dicaj.

Model yang disyorkan: suno-v6. suno-v6, suno-v6-wild dan suno-v6-mini tersedia.

Pengesahan

Jenis media yang disokong (kind)

1) Mendapatkan alamat 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 digunakan untuk main balik atau salinan sendiri; nav_url membawa Content-Disposition: attachment dan sesuai ditampal terus ke bar alamat pelayar untuk memuat turun (digunakan apabila sesetengah pelayar mudah alih tidak menyokong muat turun blob).

⚠️ Tempoh sah alamat: 7 hari — salin fail segera

url / nav_url menunjuk ke storan objek platform dan tamat secara lalai selepas 7 hari (fail diambil semula dan alamat lama memulangkan 404). Salin fail itu ke storan anda sendiri dalam tempoh 7 hari itu.

Selepas tamat tempoh lagu tidak perlu dijana semula: panggil semula POST /api/music/download-url (atau hantar refresh: true) untuk mendapatkan alamat sah yang baharu bagi lagu itu. Kumpulan endpoint ini percuma dan tidak menambah kos.

2) Memuat turun satu fail secara terus

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

Badan respons ialah strim fail (bukan JSON) dan Content-Disposition sudah membawa nama fail. Lirik dan lirik bertimestamp hanya boleh diperoleh dengan endpoint ini (download-url memulangkan alamat media sahaja, bukan lirik). Fail .lrc buat masa ini hanya disokong untuk sebahagian lagu; jika ia memulangkan success:false, bina .lrc sendiri dengan API lirik bertimestamp seperti dalam bahagian seterusnya, jangan cuba semula.

Cara mendapatkan lirik bertimestamp (.lrc)

Dua langkah disyorkan, dan ia berkesan untuk mana-mana lagu:

Langkah 1: dapatkan garis masa perkataan demi perkataan (percuma)

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

Hasilnya terus berupa tatasusunan (tiada pembalut data); setiap elemen berbentuk {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word sudah mengandungi baris baharu, jadi boleh dipecahkan mengikut baris; untuk maksud medan, penapisan bahagian instrumental dan amaran lain, lihat "Medan" dan "Nota penggunaan" dalam API lirik bertimestamp.

Langkah 2: bina .lrc sendiri daripada start_s (format masa [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 turut memuat turun .lrc yang dijana pelayan secara terus, tetapi buat masa ini hanya sebahagian lagu disokong: jika ia memulangkan success:false, bina sendiri seperti di atas — tiada keperluan mencuba semula dan pengebilan tidak terjejas.

3) Muat turun pakej

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

Gunakan sama ada song_id (satu) atau song_ids (kelompok, sehingga 50 item). Badan respons ialah strim ZIP.

4) Alamat muat turun stabil

GET /api/music/download?song_id=<id>&kind=<kind> ialah pintu masuk muat turun yang diberikan terus dalam respons lagu. Ia menerima kunci API dan sesi log masuk, berkelakuan sama seperti download-file dan sesuai dikodkan tetap dalam klien atau pemain pihak ketiga.

5) Pratonton semasa penjanaan

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 bernilai true bermakna ini alamat pratonton sementara bagi lagu yang sedang dijana; tukar ke alamat tetap setelah lagu selesai. Jika satu lagu gagal, item itu membawa medan error dan lagu lain tetap dipulangkan seperti biasa.

Nota

• Semua endpoint hanya memulangkan alamat media yang dihoskan platform; ia tidak pernah memulangkan sumber disulitkan Suno atau alamat bertandatangan sementara.
• Alamat bukan kekal — salin fail sendiri jika mahu menyimpannya lama; gunakan download-file apabila anda perlukan fail asal pada cakera.
• MIDI sesuatu stem memerlukan pemisahan stem itu sudah selesai, jika tidak ralat akan dipulangkan.