API Replace Section (แทนที่ท่อน)

อัปเดต 2026-09-18 · ทีม Suno-API

คำอธิบายเอนด์พอยต์

Replace Section สร้างช่วงเวลาหนึ่งของเพลงที่มีอยู่ใหม่ในตำแหน่งเดิม เหมาะกับการแก้เนื้อเพลงหนึ่งบรรทัดหรือเปลี่ยนท่อนใดท่อนหนึ่ง

เอนด์พอยต์: POST /api/music/replace-section

ค่าบริการ: มีค่าใช้จ่าย ปัจจุบันค่าเริ่มต้น 0.6 หยวนต่อครั้ง จำนวนที่หักจริงเป็นไปตามการตั้งราคาในระบบหลังบ้านปัจจุบัน

Max Mode / Variety: เอนด์พอยต์นี้รองรับพารามิเตอร์ทางเลือก max_mode และ variety (0-4) เมื่อเปิด max_mode ครั้งนี้จะคิดค่าบริการเป็น 2 เท่า (0.6 → 1.2 หยวนต่อครั้ง) ส่วน variety ไม่มีค่าใช้จ่ายเพิ่ม ความหมายและวิธีส่งดูได้ในหัวข้อ "พารามิเตอร์ขั้นสูง" ของ ภาพรวม API ใหม่

ระยะเวลารอและ timeout (สำคัญ): เอนด์พอยต์นี้เป็นแบบซิงโครนัส — คำสั่งจะถูกรับและส่งเข้าสู่การสร้างเมื่อคำตอบกลับมาเท่านั้น จากการวัด ส่วนใหญ่ตอบกลับภายใน 1-3 วินาที ประมาณ 10% เกิน 30 วินาที และนานที่สุดประมาณ 230 วินาที กรุณาตั้ง timeout ฝั่งไคลเอนต์ไว้ที่ 300 วินาทีขึ้นไป การไม่ได้รับคำตอบไม่ได้หมายความว่าไม่ได้สร้าง และอย่าลองซ้ำทันทีหลัง timeout (จะซ้ำคำสั่งและถูกหักเงินซ้ำ) หากการเชื่อมต่อขาด ให้ตรวจสอบภายหลังด้วย GET /api/music/songs ดูหัวข้อ "ระยะเวลารอและการตั้งค่า timeout" ใน ภาพรวม API ใหม่

พารามิเตอร์คำขอ

Headers

พารามิเตอร์บอดี

startSeconds และ endSeconds หน่วยเป็นวินาที ใส่ทศนิยมได้ และ startSeconds ต้องน้อยกว่า endSeconds โดยช่วงต้องอยู่ในความยาวของเพลงต้นฉบับ requestedAt ใช้เฉพาะเมื่อต้องส่งเวลาของคำขอ เป็น Unix timestamp หน่วยวินาที (ไม่ใช่มิลลิวินาที) ปกติข้ามได้

การแทนที่ก็เป็นงานแบบอะซิงโครนัส คลิปที่คืนอาจเริ่มที่สถานะ pending ซึ่งที่อยู่ไฟล์เสียงว่างเป็นเรื่องปกติ ให้ใช้ song_id จริงที่คืนมาเพื่อตรวจสอบผลลัพธ์สุดท้าย

ความยาวท่อน: อย่างน้อย 2 วินาที (สำคัญ)

ช่วงที่จะแทนที่ สั้นกว่า 2 วินาทีไม่ได้ จากการวัด ช่วง 1.0 / 1.2 / 1.5 วินาทีล้มเหลวทั้งหมด ส่วน 2.0 วินาทีขึ้นไปทำงานปกติ

เมื่อช่วงสั้นเกินไป แพลตฟอร์มจะไม่ตอบว่า "พารามิเตอร์ผิด" แต่จะตอบข้อความที่ตีความผิดได้ง่าย:

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

ประโยคนี้ไม่ใช่ปัญหาบัญชีหรือแพ็กเกจ แต่คือท่อนสั้นเกินไป ให้ยืดช่วงให้เกิน 2 วินาทีแล้วส่งใหม่

ตัวอย่างคำขอ

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": "เนื้อเพลงบริบททั้งหมด",
    "contextWindowLyrics": "เนื้อเพลงบริบทหน้าต่าง",
    "infillLyrics": "เนื้อเพลงหลังแทนที่",
    "style": "Mandopop, acoustic",
    "title": "เวอร์ชันแทนที่",
    "negativeTags": "noise"
  }'

คำตอบ

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "เวอร์ชันแทนที่",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

ฟิลด์ที่ใช้แทนกันได้

• 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