API Replace Section (ganti bagian)

Diperbarui 2026-09-18 · tim Suno-API

Deskripsi endpoint

Replace Section membuat ulang di tempat satu rentang waktu lagu yang sudah ada. Cocok untuk memperbaiki satu baris lirik atau mengganti satu bagian.

Endpoint: POST /api/music/replace-section

Biaya: Berbayar, saat ini default 0,6 ¥ per panggilan. 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.

Parameter permintaan

Headers

Parameter body

startSeconds dan endSeconds dalam detik dan menerima desimal; startSeconds harus lebih kecil dari endSeconds dan rentangnya harus berada dalam durasi lagu asli. requestedAt hanya dipakai bila Anda perlu mengirim waktu permintaan, sebagai timestamp Unix dalam detik (bukan milidetik); biasanya bisa dihilangkan.

Penggantian juga tugas asinkron. Clip yang dikembalikan bisa mulai pada status pending, dan alamat audio kosong saat itu normal; gunakan song_id asli yang dikembalikan untuk mengueri hasil akhir.

Panjang bagian: minimal 2 detik (penting)

Rentang yang akan diganti tidak boleh lebih pendek dari 2 detik. Dari pengukuran: rentang 1,0 / 1,2 / 1,5 detik semuanya gagal, sedangkan 2,0 detik ke atas berhasil.

Ketika rentangnya terlalu pendek, platform tidak menjawab dengan "kesalahan parameter" melainkan pesan yang mudah disalahartikan:

{"error":{"message":"You don't have access to this model. Upgrade your plan to use it.",
          "type":"bad_response_status_code","code":"bad_response_status_code"}}

Kalimat itu bukan masalah akun atau paket — bagiannya terlalu pendek. Panjangkan rentang melewati 2 detik lalu kirim ulang.

Contoh permintaan

curl -X POST https://www.suno-api.io/api/music/replace-section \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "audioId": "clip_id",
    "startSeconds": 30,
    "endSeconds": 45,
    "contextLyrics": "lirik konteks lengkap",
    "contextWindowLyrics": "lirik konteks jendela",
    "infillLyrics": "lirik pengganti",
    "style": "Mandopop, acoustic",
    "title": "Versi penggantian",
    "negativeTags": "noise"
  }'

Respons

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "Versi penggantian",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

Kolom yang kompatibel

• audioId / audio_id / clipId / clip_id
• startSeconds / start_seconds / infillStartS / infill_start_s
• endSeconds / end_seconds / infillEndS / infill_end_s
• infillLyrics / infill_lyrics / replacementLyrics / replacement_lyrics
• style / tags
• negativeTags / negative_tags