Ringkasan dokumentasi Suno API

Diperbarui 2026-09-18 · tim Suno-API

Daftar dengan alamat email dan Anda sudah bisa membuat kunci API. Satu kali pembuatan berbiaya 0,6 ¥, menghasilkan 2 lagu, dan mencakup unduhan MP3/WAV, lagu cover, Extend, pemisahan stem, serta kloning suara. URL dasar: https://www.suno-api.io.

Halaman ini mencantumkan model yang tersedia saat ini, seluruh endpoint pembuatan dan pengeditan, cara penagihan, dan urutan baca yang disarankan. Jika Anda baru pertama kali berintegrasi, bacalah dari atas ke bawah; bagian penanganan masalah 401/403/429 juga ada di sini.

Jawaban singkat

Bagaimana cara mendapatkan kunci API? Daftar dengan alamat email, buka konsol, masuk ke manajemen token, lalu buat token. Tidak perlu nomor telepon dan tidak perlu kartu bank.

Berapa biaya satu panggilan? Satu kali pembuatan berbiaya 0,6 ¥ dan menghasilkan 2 lagu. Kueri status, WAV, lirik bertimestamp, dan saran prompt gratis.

Model apa yang didukung? suno-v6 (default), suno-v6-wild, dan suno-v6-mini. Model pembuatan standar v5.5 dan yang lebih lama sudah dihentikan; karya yang sudah ada tidak terpengaruh.

Apa URL dasarnya? https://www.suno-api.io, dengan header Authorization: Bearer YOUR_API_KEY.

Model yang tersedia saat ini

Model untuk pelanggan pada pembuatan lagu standar adalah suno-v6, suno-v6-wild, dan suno-v6-mini. Jika model dikosongkan, sistem memakai suno-v6.

Model standar suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5, dan suno-v5-5 sudah dihentikan. Tugas lama mungkin masih menampilkan nama-nama itu; itu data riwayat, bukan tanda bahwa model tersebut masih bisa dipakai untuk permintaan baru. Pemisahan stem adalah pengecualian — lihat API pemisahan stem (pisah vokal/musik).

Autentikasi

Semua endpoint publik berkunci API memakai set header yang sama:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

URL dasar:

https://www.suno-api.io

Konvensi parameter umum

• number di body harus berupa angka JSON, bukan string persentase. Intensitas 50% ditulis 0.5, tidak pernah 50 atau 50%.
• boolean harus true atau false. Jangan memakai 0 atau 1 sebagai pengganti.
• Kolom bertanda "tidak" boleh dihilangkan sepenuhnya. Jika Anda belum yakin fungsi sebuah parameter, biarkan kosong agar layanan memakai perilaku defaultnya; jangan mengirim string kosong, null, atau 0 sebagai pengganti "tidak dikirim", karena 0 adalah nilai sah untuk sebagian kolom angka.
• Nama kolom peka ejaan. Setiap halaman endpoint mencantumkan nama yang disarankan dan alias yang kompatibel; kirim persis seperti pada tabel parameter. Di tempat dokumentasi menyatakan snake_case dan camelCase sama-sama diterima, jangan mengirim keduanya sekaligus.
• Setiap kolom durasi yang berakhiran _s atau Seconds diukur dalam detik dan menerima desimal. Timestamp Unix dijelaskan terpisah, termasuk apakah dalam detik atau milidetik.
• ID yang diawali pending: adalah placeholder platform, bukan song_id sungguhan. Pakai hanya di tempat endpoint secara eksplisit menyatakan dukungan placeholder; selain itu tunggu song_id yang asli.

Batas kolom teks

Melebihi batas teks mengembalikan HTTP 400 secara langsung: tidak ada yang dibuat, tidak ada pre-charge, dan tidak ada catatan tugas yang dibuat. Perhitungannya per karakter Unicode (satu aksara Han dihitung 1) dan spasi di awal/akhir ikut dihitung.

Kolom message menyebutkan kolom mana yang melanggar beserta panjang terukurnya, jadi dua angka itu sudah cukup untuk memangkasnya:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Berlaku untuk: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Satu pengecualian: kolom description pada POST /api/music/sounds dibatasi 100 karakter, karena jalur efek suara memakai batas platform yang lebih pendek.

Pembuatan asinkron dan alamat audio

Endpoint pembuatan musik secara default bekerja asinkron. Ketika respons pertama membawa status bernilai pending, submitted, atau processing, audio_url, video_url, atau cover_url yang kosong adalah hal normal dan bukan tanda tugas gagal. Simpan song_id yang asli (atau client_request_id yang dikembalikan endpoint) lalu panggil endpoint kueri yang sesuai; baca dan unduh alamat audio hanya setelah statusnya selesai.

⚠️ Alamat audio kedaluwarsa setelah 7 hari — pindahkan berkas Anda tepat waktu

audio_url, wav_url, video_url, dan alamat yang dikembalikan endpoint unduhan dilayani dari penyimpanan objek platform dan kedaluwarsa setelah 7 hari secara default (berkas didaur ulang; alamat lama mengembalikan 404 / gagal diunduh).

• Dalam 7 hari itu, pindahkan berkas ke penyimpanan Anda sendiri (penyimpanan objek Anda, CDN, atau disk server). Jangan memperlakukan alamat kami sebagai tautan berumur panjang.
• Alamat yang kedaluwarsa tidak perlu membuat ulang lagu dan tidak berbiaya tambahan: panggil lagi API kueri lagu (atau API unduh media) untuk memperoleh alamat baru yang masih berlaku bagi lagu tersebut.

Waktu tunggu dan pengaturan timeout

Endpoint pembuatan bersifat sinkron: pesanan baru diterima dan diteruskan ke platform untuk digenerate ketika responsnya tiba. Sebelum itu, layanan harus menjadwalkan akun dan melewati pemeriksaan keamanan yang diwajibkan, dan tidak ada respons antara — tidak ada endpoint lain yang bisa melihat pesanan tersebut. Jadi satu-satunya bukti andal bahwa "sesuatu sudah dibuat" adalah responsnya sendiri, bukan apa pun yang Anda amati selama menunggu.

Waktu tunggu terukur (keluarga /api/music/create di produksi, 2026-09-18 sampai 2026-09-20)

• Sekitar 10% permintaan memakan waktu lebih dari 30 detik dan sekitar 1% memakan 1–2 menit. Permintaan yang lambat biasanya berarti permintaan itu harus melewati pemeriksaan keamanan lebih dulu.
• Kolom permintaan, bentuk respons, kode kesalahan, dan penagihan tidak berubah, jadi integrasi yang sudah ada hanya perlu menaikkan timeout klien — tanpa perubahan kode lain.

Persyaratan integrasi

1. Setel timeout klien 300 detik atau lebih. Klien yang default 30, 60, atau 120 detik akan memutus koneksi saat menunggu.
2. Tidak ada respons bukan berarti tidak ada yang dibuat. Saat timeout atau koneksi terputus, pesanan bisa sudah diterima dan sedang digenerate.
3. Jangan mencoba ulang langsung setelah timeout: pengiriman ganda membuat pesanan kedua dan menagih lagi.
4. Jika koneksi terputus, daftarkan lagu Anda dengan GET /api/music/songs (terbaru dulu) beberapa saat kemudian — pesanan yang sudah diterima akan muncul normal. Kirim ulang hanya setelah Anda memastikan pesanan itu benar-benar tidak ada.
5. Saat melaporkan masalah, sertakan header respons X-Oneapi-Request-Id agar permintaan itu bisa dilacak langsung.

Tidak mau menahan koneksi lama? Gunakan mode terima-tanda-terima. POST /api/music/create dan POST /api/music/create/custom mendukung tanda terima opsional: tambahkan "accept_mode": "async" ke body (atau header X-Accept-Mode: async) dan endpoint langsung mengembalikan 202 beserta nomor tanda terima sementara pembuatan berlanjut di latar belakang; panggil GET /api/music/requests/{request_id} untuk memantau kemajuannya. Klien yang timeout-nya hanya beberapa puluh detik jadi tidak salah membaca "tidak ada respons" sebagai "tidak ada yang dibuat", dan tidak bisa tertagih dua kali karena percobaan ulang. Lihat "Mode terima-tanda-terima" di API pembuatan mode sederhana.

Sebagai referensi: python requests memakai timeout=300, urllib memakai urlopen(..., timeout=300), Node memakai req.setTimeout(300000), curl memakai --max-time 300.

Daftar endpoint yang disarankan

/api/voice/clone/* dan /api/music/generate-with-voice adalah jalur kloning suara generasi awal dan tidak disarankan untuk integrasi baru; gunakan 【Disarankan】 API profil suara sebagai gantinya.

Parameter lanjutan: Max Mode dan Variety

Endpoint pembuatan mendukung dua parameter opsional ini (mengosongkannya mempertahankan perilaku dan harga sebelumnya):

Kedua parameter ini didukung oleh: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• Harga 2× dalam praktik: endpoint yang berbiaya 0,6 ¥ per panggilan menjadi 1,2 ¥ dengan max_mode; pembuatan dengan suara pilihan berbiaya 1,2 ¥ per panggilan dan 2,4 ¥ dengan Max Mode; cover dengan suara dari 【Disarankan】 API profil suara juga 1,2 ¥ per panggilan (2,4 ¥ dengan max_mode).
• variety hanya berlaku untuk keluarga suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini); mengirimnya bersama model lain mengembalikan 400.
• Efek suara, pemisahan stem, concat, WAV, dan aksi pengeditan Studio (crop, hapus bagian, fade, balik arah, ubah kecepatan, dan seterusnya) tidak menerima kedua parameter ini — mengirimnya secara eksplisit mengembalikan 400, agar tidak ada parameter yang diabaikan diam-diam.
• variety adalah bilangan bulat mentah 0-4; style_weight dan weirdness_constraint adalah desimal dari 0 sampai 1, jadi skalanya berbeda.

Kolom respons lagu yang umum

Endpoint pembuatan, cover, extend, pemisahan, dan kueri biasanya mengembalikan array lagu dengan kolom berikut:

Empat langkah berintegrasi (contoh minimal yang berjalan)

Lakukan keempat langkah ini dan Anda sudah punya lagu pertama; daftar kolom lengkap tiap langkah ada di halaman yang sesuai pada daftar endpoint yang disarankan.

# 1) Kirim permintaan pembuatan: 0,6 ¥, menghasilkan 2 lagu
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Mandarin pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Polling tugas sampai status completed (interval 3-5 detik sudah bagus)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id yang dikembalikan di langkah 1"}'

# 3) Ambil alamat media: endpoint baca semuanya gratis; tersedia song / wav / video / cover / midi
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 yang sama", "kind": "song"}'

Jika ada masalah: 401 / 402 / 403 / 429 dibahas di referensi kesalahan; timeout dan tagihan ganda di bagian "Waktu tunggu dan pengaturan timeout" di atas; detail per endpoint di daftar endpoint yang disarankan di bawah.

Rekomendasi

• Integrasi baru sebaiknya memakai suno-v6 di sepanjang alur.
• Untuk endpoint yang menyebut harga default, jumlah yang benar-benar ditagih mengikuti konfigurasi harga back-office saat ini dan model yang diminta.
• Endpoint pembuatan biasanya mengembalikan tugas lebih dulu; baca audio akhirnya lewat /api/music/query.
• wait_completion=true memblokir sampai selesai dan cocok untuk pengujian bervolume kecil; di produksi, polling lebih disarankan.
• Endpoint pembuatan bisa sangat lama baru merespons — setel timeout klien 300 detik atau lebih, dan ingat bahwa "tidak ada respons" tidak sama dengan "tidak ada yang dibuat"; lihat "Waktu tunggu dan pengaturan timeout" di atas.
• Kemampuan unggah, cover, replace, dan WAV bergantung pada akun platform dan izin klip sumber; jika gagal, baca lebih dulu message atau error_message yang dikembalikan.

Tentang dokumentasi ini

Halaman ini disusun ulang mengikuti kemampuan yang benar-benar ditampilkan Create UI, dan integrasi baru sebaiknya membacanya lebih dulu. Dokumentasi API lama masih tersedia di bagian "Dokumentasi API lama (kompatibel)" bagi pemanggil yang ingin terus memakainya.