API kueri lagu dan riwayat

Diperbarui 2026-09-18 · tim Suno-API

Halaman ini mencakup tiga endpoint kueri gratis:

Jika Anda memakai mode tanda terima penerimaan (accept_mode=async) pada endpoint pembuatan, yang Anda pegang adalah nomor tanda terima, bukan ID lagu. Pantau kemajuannya dengan GET /api/music/requests/{request_id} lalu kembali ke endpoint di halaman ini setelah mendapat song_id asli. Lihat "Mode tanda terima penerimaan" di API pembuatan mode sederhana.

Autentikasi dan cakupan data

Ketiga endpoint memakai kunci API yang sama:

Authorization: Bearer YOUR_API_KEY

Riwayat lagu dipisahkan berdasarkan user_id pemilik kunci API. Beberapa kunci yang dibuat di bawah akun utama yang sama dapat membaca riwayat akun itu, tetapi tidak dapat membaca lagu pengguna lain atau akun subsitus lain.

Endpoint riwayat hanya mengembalikan lagu yang benar-benar dibuat. Tidak termasuk:

• catatan placeholder pembuatan yang diawali pending:;
• unggahan audio sumber dan catatan unggahan yang disempurnakan;
• hasil turunan seperti pemisahan vokal/musik dan stem;
• lagu milik pengguna lain atau akun subsitus lain.

1. Kueri status pembuatan

Mencari status saat ini dan hasil akhir dari satu atau beberapa ID lagu.

Endpoint: POST /api/music/query

Biaya: Gratis.

Headers

Parameter body

Contoh permintaan

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

Contoh respons

[
  {
    "song_id": "clip_id_1",
    "song_title": "Judul lagu",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Teks lirik",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Catatan kompatibilitas

Dokumentasi lama mungkin menampilkan song_ids sebagai array. Kini disarankan string yang dipisahkan koma, sesuai cara endpoint ini sebenarnya dipanggil.

song_ids harus berisi ID lagu asli. ID placeholder yang diawali pending: bukan song_id final dan tidak bisa dipakai di sini; mengueri hanya ID placeholder bisa mengembalikan array kosong [].

model, model_version, atau model_name platform pada respons bisa menyimpan nilai historis. Tugas baru sebaiknya memakai suno-v6, suno-v6-wild, atau suno-v6-mini; dari suno-v2 sampai suno-v5-5 sudah dihentikan, dan melihat nama itu di riwayat bukan berarti modelnya masih bisa dikirim.

Selama tugas berstatus pending, submitted, atau processing, audio_url, video_url, dan cover_url bisa kosong — itu normal untuk tugas yang belum selesai. Jangan menyimpulkan gagal hanya karena alamat kosong; gunakan status dan kueri lagi setelah statusnya selesai. Hanya jika status sudah selesai tetapi alamat tetap kosong, sebaiknya menghubungi dukungan dengan menyertakan song_id.

⚠️ Alamat audio hanya bertahan 7 hari — pindahkan berkas Anda tepat waktu

audio_url, video_url (dan alamat media lain seperti WAV) yang dikembalikan di sini dilayani dari penyimpanan objek platform dan kedaluwarsa setelah 7 hari secara default: berkas didaur ulang dan alamat lama mengembalikan 404.

• Dalam 7 hari itu, pindahkan berkas ke penyimpanan Anda sendiri; jangan anggap alamat ini sebagai tautan berumur panjang.
• Alamat yang kedaluwarsa tidak perlu membuat ulang lagu dan tidak dikenai biaya lagi: panggil lagi endpoint ini (POST /api/music/query) untuk memperoleh alamat baru yang masih berlaku bagi lagu tersebut.

2. Kueri riwayat lagu akun

Mendaftar lagu yang dibuat akun utama pemilik kunci API saat ini. Cocok untuk menyusun daftar lagu, pemilih, atau halaman riwayat Anda sendiri.

Endpoint: GET /api/music/songs

Biaya: Gratis.

Parameter query

Hasil diurutkan menurun berdasarkan created_at dan ID catatan internal, sehingga urutan halaman tetap stabil.

Menemukan kiriman yang timeout: endpoint pembuatan tidak memberi respons antara sebelum diterima. Jika klien Anda timeout atau koneksinya terputus saat mengirim, pesanan itu bisa sudah diterima dan sedang dibuat. Lihat endpoint ini (terbaru dulu): lagu yang sudah diterima muncul normal di daftar. Kirim ulang hanya setelah Anda memastikan benar-benar tidak ada, agar tidak membayar dua kali. Lihat "Waktu tunggu dan pengaturan timeout" di Ringkasan API baru.

Contoh permintaan

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "Kota di malam hari",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

Kolom respons

Endpoint daftar tidak mengembalikan prompt, kolom biaya, informasi akun, atau respons mentah. Untuk prompt dan parameter pembuatan, panggil endpoint detail lagu.

3. Kueri parameter pembuatan

Mencari prompt, gaya, model, dan lagu sumber yang disimpan platform saat lagu dibuat.

Endpoint: GET /api/music/songs/:song_id

Biaya: Gratis.

Hanya lagu milik akun utama pemilik kunci API saat ini yang bisa dibaca. Lagu pengguna lain atau akun subsitus lain selalu diperlakukan sebagai "lagu tidak ditemukan".

Parameter path

Contoh permintaan

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "Kota di malam hari",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "jalanan kota setelah hujan, lirik tentang pertemuan kembali",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "Kota di malam hari",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

Kolom parameters

Kolom prompt_view (lihat prompt, ditambahkan 2026-09-28)

prompt_view adalah struktur ternormalisasi khusus untuk "lihat prompt": ia menata data ke bagian tetap menurut jenis pembuatan, sehingga klien tidak perlu lagi memutuskan kolom mana yang ditampilkan. Ini kolom murni tambahan — kolom lama (parameters, parameter_retention) tetap memakai nama dan makna yang sama, dan klien yang tidak mengurai kolom baru sama sekali tidak terpengaruh.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Mode kustom",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Pukul empat pagi#701f37", "title_base": "Pukul empat pagi", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "elektronik guochao, sub bass dalam, synth retro",
    "style_tags": "elektronik guochao, sub bass dalam, synth retro",
    "style_source": "user", "lyrics": "...",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

Kolom yang mungkin muncul di extended: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, serta kelompok efek suara sound_type / sound_bpm / sound_key / sound_loop. Nilai kosong tidak pernah dikembalikan.

Tiga aturan tampilan (ikuti, jangan menebak):

1. Bedakan asal gaya: bila style_source=suno_derived, tampilkan "gaya (disimpulkan Suno dari deskripsi Anda)", jangan tulis "gaya yang Anda isi";
2. Prompt internal tidak pernah muncul: jenis cover dengan suara hanya mengembalikan 【persyaratan gaya】/【persyaratan cover】 yang diketik pengguna; rangka tetap yang kami susun untuk model tidak muncul di kolom mana pun (data riwayat juga sudah dibersihkan);
3. Jangan menebak parameter yang tidak disimpan: bila tidak ada di extended, berarti saat itu tidak dicatat — jelaskan alasannya lewat retention.

Catatan penyimpanan parameter

parameter_retention memisahkan "nilai kosong dikirim secara eksplisit" dari "kolom tidak pernah disimpan secara historis":

• core_parameters_available: apakah catatan tugas utama ada; pada detail yang sah biasanya true;
• extended_parameters_available: apakah catatan tugas musik lanjutan terkait ditemukan;
• sources: dari tabel data mana respons ini berasal;
• unavailable_fields: kolom yang tidak dapat dipulihkan secara andal dari riwayat; kolom ini mengembalikan null di dalam parameters.

Lagu riwayat biasa umumnya menyimpan prompt, gaya, judul saat ini, model, jenis pembuatan, dan lagu sumber, tetapi tidak menyimpan semua parameter lanjutan secara terpisah. Platform tidak pernah menebak nilai yang hilang dari generation_type.

Sebagian tugas musik lanjutan juga menyimpan prompt asli, gaya, judul, model, serta custom_mode, negative_tags, vocal_gender, style_weight, dan weirdness_constraint. Meski catatan lanjutan ada, instrumental, lyrics_mode, dan wait_audio bisa tetap tidak dapat dipulihkan.

Judul lagu bisa diubah pengguna setelahnya. Bila tugas riwayat biasa tidak menyimpan judul asli terpisah, parameters.title bisa berupa judul saat ini; bila ada catatan tugas lanjutan, judul pembuatan asli yang tersimpan di sana lebih diutamakan.

Tidak ditemukan atau tanpa izin

Kesalahan bisnis memakai amplop respons seragam. Bila lagu tidak ada atau bukan milik akun saat ini:

{
  "success": false,
  "message": "song not found"
}

Kesalahan bisnis ini saat ini dikembalikan dengan HTTP 200, jadi nilai hasilnya dari kolom success. Kunci API yang hilang, tidak valid, kedaluwarsa, atau dinonaktifkan mengembalikan HTTP 401.

Catatan keamanan

Endpoint riwayat dan detail tidak pernah mengembalikan:

• kunci API atau Token ID;
• kolom kuota, biaya, atau pengembalian dana;
• informasi akun atau respons mentah;
• kunci internal penyimpanan objek;
• kesalahan administrator atau kesalahan sumber daya internal.