API อัปโหลดแล้วคัฟเวอร์ในครั้งเดียว

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

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

อัปโหลดแล้วคัฟเวอร์ในครั้งเดียวใช้ส่งไฟล์เสียงหรือ URL เสียง แล้วสร้างเวอร์ชันคัฟเวอร์ใหม่จากเสียงต้นทางนั้น

เอนด์พอยต์: POST /api/music/upload-cover

ค่าบริการ: มีค่าใช้จ่าย ปัจจุบันค่าเริ่มต้น 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 ใหม่

เมื่อไฟล์เสียงใหญ่ ควรแยก «อัปโหลด» กับ «คัฟเวอร์» เป็นสองขั้น (แนะนำ)

เอนด์พอยต์นี้ต้องใส่เสียงทั้งไฟล์ลงในเนื้อคำขอ: เสียงยิ่งใหญ่ เนื้อคำขอยิ่งใหญ่ และเพียงการสั่นของเครือข่ายหรือ timeout ครั้งเดียวก็ตัดการรับส่งกลางทางได้ จากนั้นเซิร์ฟเวอร์จะคืน unexpected end of JSON input (HTTP 400 ไม่คิดค่าใช้จ่าย)

เมื่อเสียงเกินประมาณ 8MB เครือข่ายไม่เสถียร หรือต้องใช้ซ้ำวัสดุต้นทางเดิม ให้เปลี่ยนไปใช้แบบสองขั้น:

1. POST /api/music/upload-source อัปโหลดเสียงต้นทางก่อน — ฟรี ลองใหม่ได้ทุกเมื่อ — แล้วได้ clip_id มา
2. POST /api/music/generate-from-source ใช้ clip_id นั้นเริ่มคัฟเวอร์ — เนื้อคำขอของขั้นที่คิดเงินมีเพียงประมาณ 250 ไบต์

ดู API อัปโหลดเสียงต้นทาง, API คัฟเวอร์จากคลิปต้นทาง และหัวข้อ «ไฟล์ใหญ่และคำขอที่ถูกตัด» ท้ายหน้านี้

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

Headers

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

cover_start_s และ cover_end_s มีหน่วยเป็นวินาที ใส่ทศนิยมได้ เวลาเริ่มต้นต้องน้อยกว่าเวลาสิ้นสุด และห้ามเกินความยาวของเสียงต้นทาง หากเว้นทั้งสองฟิลด์จะใช้เสียงทั้งไฟล์ audio_weight จะแมปไปยัง metadata.control_sliders.audio_weight ของ Suno และควบคุมว่าผลลัพธ์พึ่งพาเสียงอ้างอิงมากเพียงใด รับค่า 0.0-1.0 และใส่ได้เฉพาะเมื่อในคำขอมีเสียงอ้างอิงที่ใช้ได้ใน file_url หรือ file_base64 ค่า 0 ถือว่าใช้ได้ การเว้นฟิลด์หมายถึง «ไม่ระบุ» และใช้พฤติกรรมเริ่มต้นของ Suno ต่อ instrumental และ waitAudio ต้องส่งค่าบูลีน JSON ไม่ใช่สตริง

เอนด์พอยต์อัปโหลดคืนค่าแบบอะซิงโครนัสโดยค่าเริ่มต้น เมื่อ clips[].status ในคำตอบเป็น pending การที่ audio_url ว่างเป็นเรื่องปกติ และไม่ได้หมายความว่าการอัปโหลดหรือคัฟเวอร์ล้มเหลว กรุณาเก็บ song_id จริงที่ได้มา แล้วใช้เอนด์พอยต์ค้นหาเพลงไล่ถามจนกว่าจะเสร็จก่อนอ่านที่อยู่เสียง

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

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": "เนื้อเพลงใหม่หรือทิศทางการดัดแปลง",
    "style": "Mandopop, acoustic guitar",
    "title": "เวอร์ชันคัฟเวอร์",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

คำตอบ

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "เวอร์ชันคัฟเวอร์",
        "status": "pending"
      }
    ]
  }
}

ไฟล์ใหญ่และคำขอที่ถูกตัด

วิธีที่แนะนำ: แยกอัปโหลดและคัฟเวอร์เป็นสองขั้น

เอนด์พอยต์แบบครั้งเดียว (ตัวนี้) รวมอัปโหลดและสร้างไว้ในขั้นเดียว: เนื้อคำขอขนาดใหญ่อยู่ในขั้นเดียวเท่านั้น เมื่อขาดกลางทางจึงไม่รู้ว่าสร้างไปแล้วหรือยัง และตัดสินใจยากว่าถูกหักเงินหรือไม่

สรุป: เสียงเกินประมาณ 8MB เครือข่ายไม่เสถียร หรือวัสดุเดียวกันใช้หลายครั้ง → ใช้แบบสองขั้น; เสียงเล็กมากและเครือข่ายเสถียร → เอนด์พอยต์นี้สะดวกกว่า

400 unexpected end of JSON input คืออะไร

ความหมายคือ JSON ที่เซิร์ฟเวอร์ได้รับไม่ครบถ้วน (ไม่ใช่ใส่พารามิเตอร์ผิด ไม่ใช่ปัญหาสิทธิ์หรือยอดคงเหลือ) สาเหตุที่พบบ่อย เรียงตามโอกาส:

1. เนื้อคำขอขนาดใหญ่ถูกตัดกลางการรับส่ง: ชั้นเชื่อมต่อบันทึกทั้ง «ไคลเอนต์ประกาศว่าจะส่งกี่ไบต์» และ «รับมาถึงจริงกี่ไบต์» เคสที่วัดได้: ไคลเอนต์ประกาศ 14.17MB แต่มาถึงจริงเพียง 11.8–12.4MB และคำขอทั้งสามครั้งหยุดที่ประมาณ 1.6–1.7 วินาที จำนวนไบต์ที่ขาดแตกต่างกันทุกครั้ง แสดงว่าเป็นการรับส่งที่ขาดกลางทาง ไม่ใช่ขีดจำกัดตายตัว (เซิร์ฟเวอร์ไม่ได้จำกัดขนาดเนื้อคำขอ)
2. Content-Length ไม่ตรงกับจำนวนไบต์ที่ส่งจริง: ใน Node.js การใช้ .length ของสตริง (จำนวนอักขระ UTF-16) เป็นความยาวจะคำนวณผิดเมื่อเนื้อหามีภาษาจีนหรือข้อความหลายไบต์
3. เขียนบอดีเป็นสตริงแทน Buffer ทำให้จำนวนไบต์ที่เขียนไม่ตรงกับที่ประกาศ

ทั้งสามกรณีเกิดก่อนขั้นคิดเงิน จึงไม่เกิดค่าใช้จ่าย

เช็กลิสต์ตรวจสอบฝั่งไคลเอนต์

• Content-Length ได้จาก Buffer.byteLength(json, 'utf8') (หรือ Buffer.from(json).length) — อย่าใช้ json.length
• เขียนเนื้อคำขอเป็น Buffer ไม่ใช่สตริง
• timeout ของ socket / คำขอ ≥ 300 วินาที
• เมื่อเสียงเกินประมาณ 8MB: เปลี่ยนไปใช้ file_url (เนื้อคำขอเพียงไม่กี่ร้อยไบต์) หรือใช้ multipart ของ upload-source หรือไปใช้แบบสองขั้นเลย
• คำขอ multipart อย่าตั้ง Content-Type เอง (ให้ไคลเอนต์ใส่ boundary ให้)
• พิมพ์ «จำนวนไบต์ที่ส่งจริง» แล้วเทียบกับ Content-Length
• ในแบบสองขั้น ให้ยืนยันว่าขั้นที่ 1 คืน clip_id และ status เป็นสถานะเสร็จแล้วก่อนส่งขั้นที่ 2

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

เอนด์พอยต์ที่เกี่ยวข้อง: API อัปโหลดเสียงต้นทาง (ขั้นที่ 1), API คัฟเวอร์จากคลิปต้นทาง (ขั้นที่ 2)