API แยกแทร็ก (เสียงร้องและดนตรีประกอบ)

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

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

การแยกแทร็กใช้แบ่งเพลงที่มีอยู่แล้วออกเป็นเสียงร้อง ดนตรีประกอบ หรือผลลัพธ์หลายแทร็ก ขั้นตอนการเชื่อมต่อที่แนะนำ:

1. หากเสียงต้นทางไม่ใช่เพลงที่สร้างบนแพลตฟอร์มนี้ ให้เรียก API อัปโหลดเสียงต้นทาง ก่อน
2. เรียก POST /api/music/separate เพื่อส่งงานแยกแทร็ก
3. ใช้ API สอบถามเพลงและประวัติ ไล่ถามผลลัพธ์
4. ใช้เอนด์พอยต์ดาวน์โหลดเพื่อดาวน์โหลดไฟล์เสียงของแต่ละผลลัพธ์

เอนด์พอยต์: POST /api/music/separate

ค่าบริการ: มีค่าใช้จ่าย stem_mode=two ปัจจุบันค่าเริ่มต้น 0.6 หยวนต่อครั้ง ส่วน stem_mode=twelve เป็นการแยกหลายแทร็ก ปัจจุบันค่าเริ่มต้น 3.0 หยวนต่อครั้ง ยอดหักจริงเป็นไปตามการตั้งราคาในระบบหลังบ้าน

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

การยืนยันตัวตน

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

คำอธิบาย stem_mode

คำอธิบายการแยกแทร็ก

การแยกแทร็กเป็นความสามารถคงที่และเป็นอิสระ ไม่ต้องกรอกหรือเลือกโมเดลสร้างเพลง ลูกค้าเพียงส่งเพลงต้นทางและ stem_mode เซิร์ฟเวอร์จะจัดการตามโหมด

จำนวนมาจากไหน: หนึ่งครั้งจะสร้าง 2 เวอร์ชัน (สองผลลัพธ์จากวัสดุชุดเดียวกัน) ดังนั้นจำนวน = 2 × จำนวนแทร็กของโหมดนั้น two คือ 4 รายการ twelve คือ 24 รายการ กรุณายึดความยาวจริงของอาร์เรย์ clips ในคำตอบ อย่าเขียนลูปตามจำนวนตายตัว (บางแทร็กอาจล้มเหลว ส่วนแทร็กที่สำเร็จยังคืนตามปกติ)

แต่ละโหมดคืนแทร็กใด

12 แทร็กของโหมด twelve (ชื่อถูกกำหนดตายตัวโดยแพลตฟอร์ม ลำดับอาจเปลี่ยนแปลง):

โหมด two คืนสองแทร็กคือ (Vocals) และ (Instrumental) แทร็กละ 2 เวอร์ชัน ชื่อแทร็กของ two และ twelve ล้วนเป็นชื่อตายตัว (ไม่มีชื่อเพลงต้นทาง) อย่าหวังว่าจะดูจากชื่อแล้วรู้ว่าเป็นเพลงไหน

ใช้ชื่อแทร็กเป็นคีย์เฉพาะไม่ได้ ในสองเวอร์ชันจะมีแทร็กชื่อซ้ำกัน (เช่น (Vocals) สองรายการ (Strings) สองรายการ) และการแยกหนึ่งครั้งคืนหลายแทร็ก กรุณาใช้ song_id เป็นตัวระบุเสมอ song_title ใช้เพียงแสดงผล และอย่าใช้ดัชนีอาร์เรย์ (ลำดับอาจเปลี่ยน)

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

แยกเสียงร้อง / ดนตรีประกอบ (stem_mode: "two")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

แยกหลายแทร็ก (stem_mode: "twelve")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

คำตอบ

เมื่อสำเร็จมักคืนอาร์เรย์ของผลลัพธ์การแยก แต่ละผลลัพธ์เป็นคลิปเพลงอิสระ ต้องไล่ถามต่อจน status กลายเป็นสถานะเสร็จสิ้น

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

ด้านบนแสดงเพียง 2 จาก 4 รายการ ของโหมด two จริง ๆ จะคืน 4 รายการ (2 เวอร์ชัน × {(Vocals), (Instrumental)}) โหมด twelve จะคืน 24 รายการ จำนวนจริงยึดความยาวของอาร์เรย์ clips

โดยทั่วไปลูกค้าเพียงเก็บ clips[].song_id การสอบถามและดาวน์โหลดต่อไปจะวนรอบ ID เหล่านี้

ข้อควรระวัง

• ผลลัพธ์การแยกจะไม่ปรากฏในประวัติ GET /api/music/songs (รายการนั้นคืนเฉพาะเพลงที่สร้างทั่วไป) เมื่อส่งสำเร็จให้บันทึก clips[].song_id ทันที ไม่เช่นนั้นภายหลังจะหาไม่เจอ
• แต่ละแทร็กเป็นผลงานอิสระ: แต่ละแทร็กมี song_id ของตัวเอง ต้องไล่ถามจนเสร็จและดาวน์โหลดแยกกัน
• ค่าบริการไม่เกี่ยวกับจำนวนรายการ: คิดตามครั้ง (two 0.6 หยวนต่อครั้ง twelve 3.0 หยวนต่อครั้ง) จะได้ 4 หรือ 24 รายการก็ราคาเดียวกัน
• ดาวน์โหลด: ใช้ song_id ของแทร็กนั้นกับ POST /api/music/download-url / download-file (ฟรี) หรือใช้ audio_url จากผลการสอบถามโดยตรง ส่วน MIDI ดู API ดึงไฟล์ MIDI
• อย่าส่งซ้ำ: การแยกแทร็กเป็นเอนด์พอยต์ซิงโครนัส เมื่อ timeout ให้ตรวจด้วยการสอบถามเพลงก่อน อย่าลองใหม่ทันที (จะซ้ำคำสั่งและถูกหักเงินซ้ำ)
• แทร็กที่ไม่ต้องการแล้วให้ซ่อนด้วย API ลบสเต็ม

สอบถามผลลัพธ์การแยก

เมื่อส่งสำเร็จ ให้ใช้ clips[].song_id เรียก POST /api/music/query เพื่อสอบถามผลลัพธ์

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": "stem_clip_id_1,stem_clip_id_2"
  }'

ตัวอย่างการสอบถามที่เสร็จสิ้น:

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

ดาวน์โหลดไฟล์แทร็ก

เมื่อผลลัพธ์การแยกเสร็จสิ้น สามารถดาวน์โหลดไฟล์แทร็กเดียวได้ด้วยเอนด์พอยต์ดาวน์โหลด

เอนด์พอยต์: POST /api/music/download-file

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1",
    "kind": "audio"
  }' \
  --output stem.mp3

kind ที่รองรับ:

หากต้องการดาวน์โหลดทรัพยากรที่เกี่ยวข้องของผลลัพธ์หนึ่งรายการแบบแพ็ก ให้เรียก:

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

คำอธิบายสถานะ

ข้อผิดพลาดที่พบบ่อย

หมายเหตุเรื่องความเข้ากันได้

เอกสารเวอร์ชันเก่าเคยใช้ตัวอย่างแบบออบเจ็กต์เดียว เช่น success/task_id/vocals_url/instrumental_url การแยกแทร็กเวอร์ชันปัจจุบันยึดอาร์เรย์เพลง clips[] โดยแต่ละผลลัพธ์มี song_id ของตัวเอง และการสอบถามกับดาวน์โหลดต่อไปจะวนรอบ song_id เหล่านี้

เอนด์พอยต์ที่เกี่ยวข้อง

• หากต้องการแยกแค่เสียงร้องกับดนตรีประกอบและไม่ต้องเลือกโหมด ใช้ API ลบเสียงร้อง ซึ่งเป็นรูปแบบสองแทร็กแบบเร็วของเอนด์พอยต์นี้ และปัจจุบันฟรี
• แทร็กที่ไม่ต้องการแล้วให้ซ่อนด้วย API ลบสเต็ม (ลบแบบซอฟต์ ไม่คิดค่าใช้จ่าย)
• ขอ MIDI ของแทร็กดู API ดึงไฟล์ MIDI ขอเสียง ภาพปก และสื่ออื่น ๆ ดู API ดาวน์โหลดและฟังตัวอย่างสื่อเพลง