ภาพรวมเอกสาร Suno API

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

สมัครด้วยอีเมลก็สร้างคีย์ API ได้ทันที การสร้างหนึ่งครั้งราคา 0.6 หยวน ได้ 2 เพลง และครอบคลุมการดาวน์โหลด MP3/WAV, คัฟเวอร์, Extend, สเต็ม และการโคลนเสียง URL หลัก: https://www.suno-api.io

หน้านี้รวบรวมโมเดลที่ใช้ได้ในตอนนี้ เอนด์พอยต์สำหรับสร้างและแก้ไขเพลงทั้งหมด วิธีคิดค่าบริการ และลำดับการอ่านที่แนะนำ หากคุณเพิ่งเริ่มเชื่อมต่อ ควรอ่านจากบนลงล่าง ส่วนวิธีแก้ปัญหา 401/403/429 ก็อยู่ในหน้านี้เช่นกัน

คำตอบสั้น ๆ

จะได้คีย์ API อย่างไร? สมัครด้วยอีเมล เปิดคอนโซล เข้าไปที่การจัดการโทเคนแล้วสร้างโทเคน ไม่ต้องใช้เบอร์โทรศัพท์และไม่ต้องใช้บัตรธนาคาร

เรียกหนึ่งครั้งราคาเท่าไร? การสร้างหนึ่งครั้งราคา 0.6 หยวน ได้ 2 เพลง ส่วนการสอบถามสถานะ, WAV, เนื้อเพลงพร้อมเวลากำกับ และคำแนะนำพรอมป์ต์ ฟรี

รองรับโมเดลใดบ้าง? suno-v6 (ค่าเริ่มต้น), suno-v6-wild และ suno-v6-mini ส่วนโมเดลสร้างเพลงมาตรฐาน v5.5 และเก่ากว่านั้นยกเลิกแล้ว งานที่มีอยู่เดิมไม่ได้รับผลกระทบ

URL หลักคืออะไร? https://www.suno-api.io พร้อมเฮดเดอร์ Authorization: Bearer YOUR_API_KEY

โมเดลที่ใช้ได้ในตอนนี้

โมเดลสำหรับลูกค้าที่ใช้สร้างเพลงมาตรฐานคือ suno-v6, suno-v6-wild และ suno-v6-mini ถ้าไม่ส่ง model ระบบจะใช้ suno-v6

โมเดลมาตรฐาน suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 และ suno-v5-5 ยกเลิกแล้ว งานเก่าอาจยังแสดงชื่อเหล่านี้อยู่ ซึ่งเป็นข้อมูลย้อนหลัง ไม่ได้แปลว่าโมเดลยังใช้กับคำขอใหม่ได้ ข้อยกเว้นคือสเต็ม — ดู API แยกสเต็ม (แยกเสียงร้อง/ดนตรี)

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

เอนด์พอยต์สาธารณะที่ใช้คีย์ API ทุกตัวใช้เฮดเดอร์ชุดเดียวกัน:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

URL หลัก:

https://www.suno-api.io

ข้อกำหนดทั่วไปของพารามิเตอร์

• number ในบอดีต้องเป็นตัวเลข JSON ไม่ใช่สตริงเปอร์เซ็นต์ ความเข้ม 50% ให้เขียนเป็น 0.5 ห้ามเขียน 50 หรือ 50%
• boolean ต้องเป็น true หรือ false ห้ามใช้ 0 หรือ 1 แทน
• ฟิลด์ที่ระบุว่า "ไม่" สามารถละเว้นได้ทั้งหมด หากไม่แน่ใจว่าพารามิเตอร์หนึ่งทำอะไร ให้ปล่อยว่างเพื่อให้ระบบใช้ค่าเริ่มต้น อย่าส่งสตริงว่าง null หรือ 0 แทนการ "ไม่ส่ง" เพราะ 0 เป็นค่าที่ถูกต้องของฟิลด์ตัวเลขบางตัว
• ชื่อฟิลด์ต้องสะกดให้ตรงทุกตัวอักษร แต่ละหน้าเอนด์พอยต์จะระบุชื่อที่แนะนำและชื่อพ้องที่ใช้แทนกันได้ ส่งให้ตรงตามตารางพารามิเตอร์ ในกรณีที่เอกสารบอกว่ารับทั้ง snake_case และ camelCase อย่าส่งทั้งสองพร้อมกัน
• ฟิลด์ระยะเวลาที่ลงท้ายด้วย _s หรือ Seconds นับเป็นวินาทีและรับทศนิยม ส่วน Unix timestamp อธิบายแยกไว้ รวมถึงว่านับเป็นวินาทีหรือมิลลิวินาที
• ID ที่ขึ้นต้นด้วย pending: เป็นตัวแทนชั่วคราวของแพลตฟอร์ม ไม่ใช่ song_id จริง ใช้ได้เฉพาะที่เอนด์พอยต์ระบุว่ารองรับตัวแทนชั่วคราวเท่านั้น นอกนั้นให้รอ song_id จริง

ขีดจำกัดของฟิลด์ข้อความ

เกินขีดจำกัดข้อความจะคืน HTTP 400 ทันที: ไม่มีการสร้าง ไม่มีการหักเงินล่วงหน้า และไม่เกิดเรกคอร์ดงาน การนับใช้จำนวนอักขระ Unicode (อักษรจีนหนึ่งตัวนับเป็น 1) และนับช่องว่างหัวท้ายด้วย

ฟิลด์ message จะบอกว่าฟิลด์ใดเกินและความยาวที่วัดได้ สองตัวเลขนี้ก็เพียงพอสำหรับตัดให้สั้นลง:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

ใช้กับ: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice

ข้อยกเว้นหนึ่งข้อ: ฟิลด์ description ของ POST /api/music/sounds จำกัดไว้ที่ 100 อักขระ เพราะเส้นทางเอฟเฟกต์เสียงใช้ขีดจำกัดที่สั้นกว่าของแพลตฟอร์ม

การสร้างแบบอะซิงโครนัสและที่อยู่ไฟล์เสียง

เอนด์พอยต์สร้างเพลงทำงานแบบอะซิงโครนัสเป็นค่าเริ่มต้น เมื่อคำตอบแรกมี status เป็น pending, submitted หรือ processing การที่ audio_url, video_url หรือ cover_url ว่างเปล่าเป็นเรื่องปกติ ไม่ได้แปลว่างานล้มเหลว ให้บันทึก song_id จริง (หรือ client_request_id ที่เอนด์พอยต์คืนมา) แล้วเรียกเอนด์พอยต์สอบถามที่ตรงกัน อ่านและดาวน์โหลดที่อยู่ไฟล์เสียงเมื่อสถานะเสร็จสมบูรณ์แล้วเท่านั้น

⚠️ ที่อยู่ไฟล์เสียงหมดอายุใน 7 วัน — โอนไฟล์ของคุณให้ทันเวลา

audio_url, wav_url, video_url และที่อยู่ที่เอนด์พอยต์ดาวน์โหลดคืนมา ให้บริการจากที่เก็บออบเจ็กต์ของแพลตฟอร์ม และ หมดอายุใน 7 วันเป็นค่าเริ่มต้น (ไฟล์จะถูกเก็บคืน ที่อยู่เก่าจะคืน 404 / ดาวน์โหลดไม่ได้)

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

ระยะเวลารอและการตั้งค่า timeout

เอนด์พอยต์สร้างเพลงทำงานแบบ ซิงโครนัส: คำสั่งจะถูกรับและส่งต่อให้แพลตฟอร์มสร้างก็ต่อเมื่อคำตอบเดินทางกลับมาเท่านั้น ก่อนหน้านั้นระบบต้องจัดสรรบัญชีและผ่านการตรวจสอบความปลอดภัยที่จำเป็น และไม่มีการตอบกลับระหว่างทาง กล่าวคือไม่มีเอนด์พอยต์อื่นมองเห็นคำสั่งนี้ได้ ดังนั้นหลักฐานที่เชื่อถือได้ของคำว่า "สร้างอะไรไปแล้วหรือยัง" คือตัวคำตอบเอง ไม่ใช่สิ่งที่คุณสังเกตได้ระหว่างรอ

ระยะเวลารอที่วัดได้ (กลุ่ม /api/music/create บน production, 2026-09-18 ถึง 2026-09-20)

• ประมาณ 10% ของคำขอใช้เวลานานกว่า 30 วินาที และประมาณ 1% ใช้เวลา 1–2 นาที คำขอที่ช้ามักหมายความว่ารอบนั้นต้องผ่านการตรวจสอบความปลอดภัยก่อน
• ฟิลด์คำขอ รูปแบบคำตอบ รหัสข้อผิดพลาด และการคิดค่าบริการไม่เปลี่ยน ดังนั้น การเชื่อมต่อเดิมเพียงต้องเพิ่ม timeout ฝั่งไคลเอนต์ ไม่ต้องแก้โค้ดอื่น

ข้อกำหนดในการเชื่อมต่อ

1. ตั้ง timeout ฝั่งไคลเอนต์ ตั้งแต่ 300 วินาทีขึ้นไป ไคลเอนต์ที่ตั้งค่าเริ่มต้น 30, 60 หรือ 120 วินาทีจะตัดการเชื่อมต่อระหว่างรอ
2. ไม่มีคำตอบไม่ได้แปลว่ายังไม่มีการสร้างอะไร เมื่อ timeout หรือการเชื่อมต่อขาด คำสั่งอาจถูกรับไว้และกำลังสร้างอยู่แล้ว
3. อย่าลองซ้ำทันทีหลัง timeout: การส่งซ้ำจะสร้างคำสั่งที่สองและถูกคิดเงินอีกครั้ง
4. หากการเชื่อมต่อขาด ให้เรียกดูเพลงด้วย GET /api/music/songs (ใหม่สุดก่อน) หลังจากผ่านไปสักครู่ คำสั่งที่ถูกรับไว้จะปรากฏตามปกติ ส่งซ้ำก็ต่อเมื่อยืนยันแล้วว่าคำสั่งนั้นหายไปจริง
5. เมื่อแจ้งปัญหา ให้แนบเฮดเดอร์คำตอบ X-Oneapi-Request-Id เพื่อให้ค้นหาคำขอนั้นได้โดยตรง

ไม่อยากถือการเชื่อมต่อนาน? ใช้โหมดรับใบรับคำสั่ง POST /api/music/create และ POST /api/music/create/custom รองรับใบรับคำสั่งแบบเลือกได้: เพิ่ม "accept_mode": "async" ลงในบอดี (หรือเฮดเดอร์ X-Accept-Mode: async) เอนด์พอยต์จะคืน 202 ทันทีพร้อมเลขใบรับคำสั่ง ขณะที่การสร้างยังทำงานเบื้องหลัง จากนั้นเรียก GET /api/music/requests/{request_id} เพื่อดูความคืบหน้า ไคลเอนต์ที่มี timeout เพียงไม่กี่สิบวินาทีจึงอ่าน "ไม่มีคำตอบ" ผิดเป็น "ยังไม่มีการสร้าง" ไม่ได้ และก็ถูกคิดเงินซ้ำจากการลองใหม่ไม่ได้เช่นกัน ดูหัวข้อ "โหมดรับใบรับคำสั่ง" ใน API สร้างเพลงโหมดง่าย

สำหรับอ้างอิง: python requests ใช้ timeout=300, urllib ใช้ urlopen(..., timeout=300), Node ใช้ req.setTimeout(300000), curl ใช้ --max-time 300

รายการเอนด์พอยต์ที่แนะนำ

/api/voice/clone/* และ /api/music/generate-with-voice เป็น เส้นทางโคลนเสียงรุ่นแรกและไม่แนะนำสำหรับการเชื่อมต่อใหม่ ให้ใช้ 【แนะนำ】 API โปรไฟล์เสียง แทน

พารามิเตอร์ขั้นสูง: Max Mode และ Variety

เอนด์พอยต์สร้างเพลงรองรับพารามิเตอร์ทางเลือกสองตัวนี้ (ถ้าไม่ส่ง จะคงพฤติกรรมและราคาเดิม):

พารามิเตอร์สองตัวนี้รองรับโดย: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech

• ราคาสองเท่าในทางปฏิบัติ: เอนด์พอยต์ที่ 0.6 หยวนต่อครั้งจะกลายเป็น 1.2 หยวนเมื่อเปิด max_mode; สร้างเพลงด้วยเสียงที่เลือก ราคา 1.2 หยวนต่อครั้ง และ 2.4 หยวนเมื่อเปิด Max Mode; การคัฟเวอร์ด้วยเสียงของ 【แนะนำ】 API โปรไฟล์เสียง ก็เป็น 1.2 หยวนต่อครั้งเช่นกัน (2.4 หยวนเมื่อเปิด max_mode)
• variety ใช้ได้เฉพาะตระกูล suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini); ถ้าส่งพร้อมโมเดลอื่นจะคืน 400
• เอฟเฟกต์เสียง, สเต็ม, concat, WAV และการแก้ไขใน Studio (crop, ลบช่วง, fade, กลับด้าน, ปรับความเร็ว และอื่น ๆ) ไม่รับพารามิเตอร์สองตัวนี้ — ถ้าส่งมาโดยตรงจะคืน 400 เพื่อไม่ให้พารามิเตอร์ใดถูกละเลยอย่างเงียบ ๆ
• variety เป็นจำนวนเต็มดิบ 0-4 ส่วน style_weight และ weirdness_constraint เป็นทศนิยม 0 ถึง 1 สเกลจึงต่างกัน

ฟิลด์คำตอบเพลงที่พบบ่อย

เอนด์พอยต์สร้างเพลง, คัฟเวอร์, extend, แยกสเต็ม และสอบถาม มักคืนอาร์เรย์ของเพลงที่มีฟิลด์เหล่านี้:

สี่ขั้นตอนการเชื่อมต่อ (ตัวอย่างขั้นต่ำที่ใช้ได้จริง)

ทำครบสี่ขั้นนี้ก็ได้เพลงแรกแล้ว รายการฟิลด์เต็มของแต่ละขั้นอยู่ในหน้าที่ตรงกันในรายการเอนด์พอยต์ที่แนะนำ

# 1) ส่งคำสั่งสร้าง: 0.6 หยวน ได้ 2 เพลง
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Mandarin pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) วนเรียกงานจนกว่า status จะเป็น completed (ทุก 3-5 วินาทีเป็นจังหวะที่เหมาะสม)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id ที่ได้จากขั้นที่ 1"}'

# 3) ขอที่อยู่มีเดีย: เอนด์พอยต์อ่านฟรีทั้งหมด; มี song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id เดิม", "kind": "song"}'

เมื่อเกิดปัญหา: 401 / 402 / 403 / 429 อธิบายไว้ใน เอกสารข้อผิดพลาด; timeout และการคิดเงินซ้ำ อยู่ในหัวข้อ "ระยะเวลารอและการตั้งค่า timeout" ด้านบน; รายละเอียดของแต่ละเอนด์พอยต์ อยู่ในรายการเอนด์พอยต์ที่แนะนำด้านล่าง

คำแนะนำ

• การเชื่อมต่อใหม่ควรใช้ suno-v6 ตลอด
• เอนด์พอยต์ที่ระบุราคาเริ่มต้น จำนวนที่เก็บจริงเป็นไปตามการตั้งราคาในระบบหลังบ้านปัจจุบันและโมเดลที่ขอ
• เอนด์พอยต์สร้างเพลงมักคืนงานก่อน; ให้อ่านไฟล์เสียงสุดท้ายผ่าน /api/music/query
• wait_completion=true จะบล็อกรอจนเสร็จ เหมาะกับการทดสอบปริมาณน้อย; บน production ควรใช้วิธีวนเรียก
• เอนด์พอยต์สร้างเพลงอาจใช้เวลานานมากกว่าจะคืนค่า — ตั้ง timeout ฝั่งไคลเอนต์ตั้งแต่ 300 วินาทีขึ้นไป และจำไว้ว่า "ไม่มีคำตอบ" ไม่เหมือนกับ "ยังไม่มีการสร้าง"; ดูหัวข้อ "ระยะเวลารอและการตั้งค่า timeout" ด้านบน
• ความสามารถด้านอัปโหลด, คัฟเวอร์, replace และ WAV ขึ้นกับบัญชีแพลตฟอร์มและสิทธิ์ของคลิปต้นทาง; เมื่อล้มเหลว ให้อ่าน message หรือ error_message ที่คืนมาก่อน

เกี่ยวกับเอกสารนี้

หน้านี้จัดเรียงใหม่ตามความสามารถที่ Create UI แสดงจริง และการเชื่อมต่อใหม่ควรอ่านหน้านี้ก่อน เอกสาร API เวอร์ชันเก่ายังอยู่ในหัวข้อ "เอกสาร API รุ่นเก่า (เข้ากันได้)" สำหรับผู้ที่ต้องการใช้ต่อ