API unggah lalu cover sekali jalan

Diperbarui 2026-09-18 · tim Suno-API

Deskripsi endpoint

Unggah lalu cover sekali jalan mengirim berkas audio atau URL audio dan membuat versi cover baru dari audio sumber tersebut.

Endpoint: POST /api/music/upload-cover

Biaya: Berbayar, saat ini default 0,6 ¥ per panggilan. Endpoint ini adalah "unggah lalu cover", bukan mengunggah sampul gambar. Jumlah yang benar-benar ditagih mengikuti konfigurasi harga di back-office saat ini.

Max Mode / Variety: endpoint ini mendukung parameter opsional max_mode dan variety (0-4). Dengan max_mode aktif, panggilan ini ditagih 2× harga (0,6 → 1,2 ¥ per panggilan); variety tidak menambah biaya. Arti dan cara mengirimnya ada di bagian "Parameter lanjutan" pada Ringkasan API baru.

Waktu tunggu dan timeout (penting): ini endpoint sinkron — pesanan baru diterima dan diteruskan ke pembuatan saat respons tiba. Dari pengukuran, sebagian besar permintaan merespons dalam 1-3 detik, sekitar 10% melewati 30 detik, dan terlama sekitar 230 detik. Setel timeout klien 300 detik atau lebih; tidak ada respons bukan berarti tidak ada yang dibuat, dan jangan mencoba ulang langsung setelah timeout (itu menduplikasi pesanan dan menagih dua kali). Jika koneksi terputus, periksa lagi nanti dengan GET /api/music/songs. Lihat "Waktu tunggu dan pengaturan timeout" di Ringkasan API baru.

Saat audio besar, sebaiknya pisahkan "unggah" dan "cover" menjadi dua langkah (disarankan)

Endpoint ini mengharuskan seluruh audio masuk ke body permintaan: makin besar audio, makin besar body-nya, dan satu gangguan jaringan atau timeout memotong transfer di tengah jalan, lalu server mengembalikan unexpected end of JSON input (HTTP 400, tanpa biaya).

Bila audio melewati sekitar 8 MB, jaringan tidak stabil, atau materi sumber yang sama akan dipakai ulang, beralihlah ke bentuk dua langkah:

1. POST /api/music/upload-source mengunggah audio sumber lebih dulu — gratis, bisa diulang kapan saja — dan memberi clip_id;
2. POST /api/music/generate-from-source memulai cover dengan clip_id itu — body pada langkah berbayar hanya sekitar 250 byte.

Lihat API unggah audio sumber, API cover dari clip sumber, dan "Berkas besar dan permintaan yang terpotong" di akhir halaman ini.

Parameter permintaan

Headers

Parameter body

cover_start_s dan cover_end_s dalam satuan detik dan boleh desimal; waktu mulai harus lebih kecil dari waktu selesai dan tidak boleh melebihi durasi audio sumber. Bila kedua kolom dihilangkan, seluruh audio dipakai. audio_weight dipetakan ke metadata.control_sliders.audio_weight milik Suno dan mengatur seberapa besar hasil bersandar pada audio referensi; nilainya 0.0-1.0 dan hanya boleh disertakan bila permintaan memuat audio referensi yang sah di file_url atau file_base64. 0 adalah nilai yang sah; menghilangkan kolom berarti "tidak ditentukan" dan mengikuti perilaku default Suno. instrumental dan waitAudio harus boolean JSON, bukan string.

Endpoint unggah mengembalikan secara asinkron secara default. Selama clips[].status pada respons masih pending, audio_url yang kosong adalah hal normal dan bukan berarti unggahan atau cover gagal; simpan song_id asli yang dikembalikan dan panggil endpoint pencarian lagu sampai selesai sebelum membaca alamat audio.

Contoh permintaan

curl -X POST https://www.suno-api.io/api/music/upload-cover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "prompt": "Lirik baru atau arah adaptasi",
    "style": "Mandopop, acoustic guitar",
    "title": "Versi cover",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

Respons

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Versi cover",
        "status": "pending"
      }
    ]
  }
}

Berkas besar dan permintaan yang terpotong

Disarankan: pisahkan unggah dan cover menjadi dua langkah

Endpoint sekali jalan (yang ini) menggabungkan unggah dan pembuatan dalam satu langkah: body besar berada di satu-satunya langkah itu, jadi saat terputus Anda tidak tahu apakah ada yang dibuat maupun apakah ada biaya yang ditarik.

Kesimpulan: audio di atas sekitar 8 MB, jaringan tidak stabil, atau materi yang sama dipakai beberapa kali → gunakan bentuk dua langkah; audio sangat kecil di jaringan stabil → endpoint ini lebih praktis.

Apa arti 400 unexpected end of JSON input

Artinya JSON yang diterima server tidak lengkap (bukan parameter salah, bukan masalah izin atau saldo). Penyebab umum, diurutkan dari yang paling mungkin:

1. Body besar terpotong di tengah transfer: lapisan masuk mencatat baik "berapa byte yang dideklarasikan klien" maupun "berapa byte yang benar-benar tiba". Kasus terukur: klien mendeklarasikan 14,17 MB tetapi hanya 11,8–12,4 MB yang tiba, dan ketiga permintaan berhenti di sekitar 1,6–1,7 detik; jumlah byte yang hilang berbeda setiap kali, menandakan transfer terputus dan bukan batas tetap (server tidak membatasi ukuran body permintaan).
2. Content-Length tidak cocok dengan byte yang benar-benar dikirim: di Node.js, memakai .length string (jumlah karakter UTF-16) sebagai panjang akan salah begitu isinya mengandung bahasa Mandarin atau teks multi-byte lain.
3. Menulis body sebagai string alih-alih Buffer, sehingga byte yang ditulis tidak sesuai dengan yang dideklarasikan.

Ketiganya terjadi sebelum penagihan, jadi tidak muncul biaya.

Daftar periksa mandiri di sisi klien

• Content-Length berasal dari Buffer.byteLength(json, 'utf8') (atau Buffer.from(json).length) — jangan pakai json.length;
• Body permintaan ditulis sebagai Buffer, bukan string;
• Timeout socket / permintaan ≥ 300 detik;
• Bila audio melewati sekitar 8 MB: pakai file_url (body hanya beberapa ratus byte), atau unggahan multipart dari upload-source, atau langsung ke bentuk dua langkah;
• Pada permintaan multipart, jangan setel Content-Type sendiri (biarkan klien menambahkan boundary);
• Cetak "byte yang benar-benar dikirim" dan bandingkan dengan Content-Length;
• Pada bentuk dua langkah, pastikan langkah 1 mengembalikan clip_id dengan status selesai sebelum mengirim langkah 2.

Kesalahan yang sering muncul

Endpoint terkait: API unggah audio sumber (langkah 1), API cover dari clip sumber (langkah 2).