API สร้างเพลงโหมดกำหนดเอง

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

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

โหมดกำหนดเองเหมาะเมื่อคุณมีเนื้อเพลง สไตล์ และชื่อเพลงพร้อมแล้ว และต้องการควบคุมเสียงที่ร้อง ระดับอิทธิพลของสไตล์ และระดับความสุ่มของการสร้าง

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

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

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

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

คำอธิบายพารามิเตอร์ขั้นสูง

เพศของเสียง vocal_gender

• ส่ง m หรือ male สำหรับเสียงชาย, f หรือ female สำหรับเสียงหญิง
• ระบบจะปรับ male และ female ให้เป็น m และ f ตามลำดับ
• เมื่อ instrumental=true จะไม่ส่งพารามิเตอร์เพศของเสียงไปยังบริการสร้างเพลง

อิทธิพลของสไตล์ style_weight

ควบคุมว่าผลลัพธ์ยึดตาม style_tags มากเพียงใด ยิ่งค่าสูง ผลลัพธ์ยิ่งมีแนวโน้มตามแท็กสไตล์ที่กรอก

ความสุ่ม weirdness_constraint

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

พารามิเตอร์ตัวเลขทั้งสองอยู่ในช่วง 0.0 ถึง 1.0 และ 0 เป็นค่าที่ระบุได้อย่างชัดเจน การไม่ส่งฟิลด์เลยเท่านั้นจึงหมายถึง "ไม่ระบุ"

ขณะกรอก โปรดทราบว่าค่าเหล่านี้เป็นทศนิยมตามสัดส่วน ไม่ใช่จำนวนเต็มเปอร์เซ็นต์ แนวทางที่แนะนำ: 0.0–0.3 อนุรักษ์นิยม, 0.4–0.6 สมดุล, 0.7–1.0 เชิงทดลองมากขึ้น หากไม่มีความชอบชัดเจนให้ใช้ 0.5 หรือปล่อยว่าง ตัวอย่าง: weirdness_constraint: 0.5 ห้ามกรอก 50 หรือ 50%

เมื่อ instrumental=true จะได้เพลงบรรเลง เนื้อเพลงและเพศของเสียงจึงไม่ทำงานเหมือนเพลงที่มีเสียงร้อง หากต้องการเสียงร้องให้ส่ง false หรือไม่ส่งฟิลด์นี้ ฟิลด์บูลีนต้องใช้ true/false ของ JSON ไม่ใช่สตริง

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

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nกลางคืนทอดลงบนผืนทะเล\nลมเย็นยามค่ำผ่านหน้าต่าง',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'ลมเย็นริมทะเล',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

โหมดใบรับคำสั่ง (ไม่บังคับ)

เอนด์พอยต์นี้รองรับ โหมดใบรับคำสั่ง จาก API สร้างเพลงโหมดง่าย ด้วย: เมื่อใส่ "accept_mode": "async" ในบอดี (หรือเฮดเดอร์ X-Accept-Mode: async) เอนด์พอยต์จะคืน 202 และเลขใบรับคำสั่งทันที การสร้างยังทำงานเบื้องหลัง และติดตามความคืบหน้าด้วย GET /api/music/requests/{request_id}

เหมาะกับไคลเอนต์ที่ไม่ควรถือการเชื่อมต่อนาน หรือไม่ต้องการให้ timeout ถูกตีความว่า "ไม่ได้สร้าง" หากไม่ส่งพารามิเตอร์นี้ พฤติกรรมเหมือนเดิมทุกอย่าง

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "ลมเย็นริมทะเล",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

โครงสร้างคำตอบและวิธีตรวจสอบเป็นระยะดูได้ในหัวข้อ "โหมดใบรับคำสั่ง" ของ API สร้างเพลงโหมดง่าย

การตรวจสอบพารามิเตอร์

กรณีต่อไปนี้คืน HTTP 400 และ message ของข้อผิดพลาดจะระบุฟิลด์ที่ไม่ถูกต้อง:

• style_weight หรือ weirdness_constraint ไม่ใช่ตัวเลข
• ค่าตัวเลขน้อยกว่า 0.0 หรือมากกว่า 1.0
• vocal_gender ไม่ใช่หนึ่งใน m, f, male, female

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

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

ข้อความผิดพลาดมีรูปแบบ style_tags must not exceed 1000 characters; received 2772: คำแรกคือชื่อฟิลด์ที่เกิน และท้ายคือจำนวนที่นับได้ เมื่อได้ 400 จึงตัดตามสองตัวเลขนี้ได้ทันที ไม่ต้องลองทีละฟิลด์ ส่วนข้อกำหนดทั่วไปอยู่ใน "ขีดจำกัดฟิลด์ข้อความ" ของ ภาพรวม API ใหม่

คำตอบ

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

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

การเชื่อมต่อใหม่ควรใช้ snake_case ให้สม่ำเสมอ หากคำขอเดียวกันส่งทั้ง snake_case และ camelCase ค่าของ snake_case จะมีผลก่อน