API Replace Section (ganti bahagian)

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

Penerangan endpoint

Replace Section menjana semula satu julat masa lagu yang sedia ada di tempatnya. Sesuai untuk membetulkan satu baris lirik atau menggantikan satu bahagian.

Endpoint: POST /api/music/replace-section

Pengebilan: Berbayar, kini lalai 0.6 ¥ setiap panggilan. Jumlah yang benar-benar dicaj mengikut tetapan harga semasa dalam back-office.

Max Mode / Variety: endpoint ini menyokong parameter pilihan max_mode dan variety (0-4). Dengan max_mode dihidupkan, panggilan ini dibilkan pada 2× harga (0.6 → 1.2 ¥ setiap panggilan); variety tidak menambah kos. Maksud dan cara menghantarnya ada dalam bahagian "Parameter lanjutan" pada Gambaran keseluruhan API baharu.

Masa menunggu dan timeout (penting): ini endpoint segerak — pesanan hanya diterima dan dihantar ke penjanaan apabila respons tiba. Berdasarkan ukuran, kebanyakan permintaan membalas dalam 1-3 saat, kira-kira 10% melebihi 30 saat dan paling lama sekitar 230 saat. Tetapkan timeout klien kepada 300 saat atau lebih; tiada respons tidak bermakna tiada apa-apa dijana, dan jangan cuba semula sejurus selepas timeout (ia menggandakan pesanan dan mencaj dua kali). Jika sambungan terputus, periksa kemudian dengan GET /api/music/songs. Lihat "Masa menunggu dan tetapan timeout" dalam Gambaran keseluruhan API baharu.

Parameter permintaan

Headers

Parameter body

startSeconds dan endSeconds dalam saat dan menerima perpuluhan; startSeconds mesti kurang daripada endSeconds dan julatnya mesti berada dalam tempoh lagu asal. requestedAt hanya digunakan apabila anda perlu menghantar masa permintaan, sebagai cap masa Unix dalam saat (bukan milisaat); biasanya boleh ditinggalkan.

Penggantian juga tugasan tak segerak. Klip yang dikembalikan mungkin bermula pada status pending, dan alamat audio kosong ketika itu adalah normal; gunakan song_id sebenar yang dikembalikan untuk menanyakan hasil akhir.

Panjang bahagian: sekurang-kurangnya 2 saat (penting)

Julat yang hendak diganti tidak boleh lebih pendek daripada 2 saat. Berdasarkan ukuran: julat 1.0 / 1.2 / 1.5 saat semuanya gagal, manakala 2.0 saat ke atas berjaya.

Apabila julat terlalu pendek, platform tidak membalas dengan "ralat parameter" tetapi dengan mesej yang mudah disalahtafsirkan:

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

Ayat itu bukan masalah akaun atau pakej — bahagiannya terlalu pendek. Panjangkan julat melebihi 2 saat dan hantar semula.

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 penuh",
    "contextWindowLyrics": "lirik konteks tetingkap",
    "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": {}
  }
}

Medan serasi

• 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