【แนะนำ】 API โปรไฟล์เสียง

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

✅ แนะนำให้ใช้เส้นทางนี้สำหรับการเชื่อมต่อใหม่ จากผลการประเมินจริงของผู้ใช้จำนวนมาก เพลงที่สร้างด้วยเส้นทางนี้รักษาเสียงต้นฉบับได้ดี เสียงร้องในผลงานสำเร็จรูปจะใกล้เคียงกับเจ้าของเสียงในตัวอย่างที่คุณอัปโหลดมากกว่า จึงเป็นเส้นทางที่เราแนะนำให้ลูกค้าในตอนนี้

เปรียบเทียบ: API โคลนเสียงและสร้างเพลงด้วยเสียงที่ระบุ เดิมยังใช้ได้ แต่เมนูระบุว่า "ไม่แนะนำ" และไม่แนะนำสำหรับการเชื่อมต่อใหม่

• วันที่เอกสาร: 2026-09-26
• ขอบเขต: สร้างเสียงของคุณเอง → ใช้เสียงนั้นคัฟเวอร์เพลงที่เลือก / ร้องเพลงใหม่ → ติดตามความคืบหน้า → ดาวน์โหลดผลงาน
• ทุกเอนด์พอยต์ ฟิลด์ และคำตอบได้รับการตรวจสอบด้วยการเรียกจริง (หัวข้อที่ระบุว่า "วัดผล" คือรายการที่ตรวจสอบอย่างละเอียด)

หมายเหตุ: เอกสารนี้กล่าวถึงเฉพาะเอนด์พอยต์ที่คุณต้องเรียกใช้ ส่วนการจัดการวัสดุ การจัดคิวงาน และการตรวจสอบเนื้อหา เซิร์ฟเวอร์ทำให้อัตโนมัติ ฝั่งไคลเอนต์ไม่ต้องทำ

0. เริ่มต้นในห้านาที

แค่สี่ขั้นตอนก็ได้เพลงสำเร็จรูปสองเพลงจากตัวอย่างเสียงหนึ่งชิ้น

① สร้างเสียง    POST /api/music/voice-profile/create      → รับ voice_id (status=ready)
② คัฟเวอร์      POST /api/music/voice-profile/cover       → รับ song_id 2 รายการทันที
③ ติดตาม        POST /api/music/query                     → โพลจนถึง status=completed
④ ดาวน์โหลด     GET  /api/music/download?song_id=…&kind=mp3

ตัวอย่างน้อยที่สุด (curl):

API_KEY="sk-คีย์ของคุณ"
BASE="https://www.suno-api.io"

# ① สร้างเสียง (อัปโหลดตัวอย่างเสียง แนะนำ 10 วินาทีขึ้นไป ไม่เกิน 10MB)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=เสียงของฉัน" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② ใช้เสียงนี้คัฟเวอร์เพลงหนึ่งเพลง (song_clip_id = clip id ของเพลงที่จะคัฟเวอร์)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\nเนื้อเพลง…",
        "style_requirements": "โฟล์กช้า ๆ กีตาร์อะคูสติก",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ โพล (ส่งหลาย id ครั้งเดียว คั่นด้วยเครื่องหมายจุลภาค)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ ดาวน์โหลด mp3 เมื่อเสร็จ (ต้อง status=completed เท่านั้นจึงได้ไฟล์)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. ข้อตกลงทั่วไป

1.1 โดเมนและสภาพแวดล้อม

ทุกพาธด้านล่างเป็นพาธสัมพัทธ์กับ Base URL เช่นที่อยู่เต็มของ POST /api/music/voice-profile/create คือ https://www.suno-api.io/api/music/voice-profile/create

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

ทุกเอนด์พอยต์ใช้เฮดเดอร์เดียวกัน โดยค่าคือ API Key ที่คุณสร้างในคอนโซล:

Authorization: Bearer sk-xxxxxxxx

• คำนำหน้า Bearer จะใส่หรือไม่ใส่ก็ได้ เช่นเดียวกับ sk- (Authorization: sk-xxx ก็ใช้ได้)
• คีย์หายหรือไม่ถูกต้อง → HTTP 401 เนื้อหาคำตอบเป็น {"success":false,"message":"…"} (ข้อความเปลี่ยนตามภาษาของคำขอ)
• แต่ละคีย์เห็นและจัดการได้เฉพาะเพลงและเสียงของบัญชีตัวเองเท่านั้น

1.3 รูปแบบเนื้อหาคำขอ

• สร้างเสียง: แนะนำ multipart/form-data (อัปโหลดไฟล์) และรองรับ application/json (ส่ง URL หรือ base64)
• เอนด์พอยต์อื่น: application/json

1.4 เปลือกคำตอบสองแบบ (ลูกค้าต้องรู้แค่สองแบบนี้)

เอนด์พอยต์กลุ่ม "จัดการเสียง" (create / create-from-clip / list / detail / delete) ใช้เปลือกงานธุรกิจ:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

"คัฟเวอร์ด้วยเสียง" ผ่านช่องทางสร้างเพลง ใช้เปลือกการสร้าง: สำเร็จคือ code/message/data ล้มเหลวคือออบเจกต์ error:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

วิธีตัดสิน: ดูรหัสสถานะ HTTP ก่อน แล้วดู success === false สุดท้ายดู code !== 200 หรือมี error ความล้มเหลวทางธุรกิจไม่ได้การันตีว่า HTTP จะไม่ใช่ 200 (เอนด์พอยต์จัดการเสียงเมื่อผิดพลาดยังคืน HTTP 200) จึงดูแค่รหัสสถานะไม่ได้

1.5 ความคงที่ของการเรียกซ้ำ (idempotency)

การสร้างเสียง (รวม "สร้างจากไฟล์เสียงที่มีอยู่") คงที่จริง: ภายใต้คีย์เดียวกัน การส่ง client_request_id เดิมซ้ำจะสร้างเสียงเพียงรายการเดียว ครั้งที่สองจะคืนผลลัพธ์ครั้งแรกโดยตรง (success=true, voice_id เดิม) วิธีใช้คือให้ไคลเอนต์สร้าง id เอง (เช่น UUID) แล้วใช้ค่าเดิมเมื่อลองใหม่หลังหมดเวลา

การส่งคัฟเวอร์ไม่ทำการตัดข้อมูลซ้ำระดับคำขอ (เป็นการสร้างที่มีค่าใช้จ่าย) จึงควรทราบสองเรื่อง:

1. ตัวระบุการส่งอยู่ในเฮดเดอร์ X-Create-Ui-Client-Request-Id: <id การส่งของคุณ> มันจะถูกเขียนลงบันทึกงานฝั่งเซิร์ฟเวอร์เพื่อให้ตรวจสอบย้อนหลังได้ แต่ไม่ป้องกันการคิดเงินซ้ำ
2. หมดเวลา ≠ ล้มเหลว คำขออาจถูกรับไปแล้วและกำลังสร้าง ควรตรวจด้วย GET /api/music/songs?p=1&page_size=20 (พารามิเตอร์แบ่งหน้าคือ p / page_size และเขียนแบบเข้ากันได้คือ ps) ก่อนลองใหม่ ว่ามีเพลงใหม่ที่ generation_type=voice_profile_cover โผล่มาหรือยัง ถ้าไม่มีจึงส่งซ้ำ

เนื้อหาของ create และ create-from-clip ก็มีฟิลด์ client_request_id (ดู §3, §4)

1.6 ภาพรวมค่าบริการ

ราคาอ่านได้ทุกเมื่อจากเอนด์พอยต์สาธารณะ จึงไม่ควรเขียนตายตัว (ดู §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← ราคาพื้นฐานของการคัฟเวอร์ด้วยเสียง
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← ราคาโคลนแบบเสริม
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

การคัฟเวอร์ใช้รูปแบบหักล่วงหน้า + คืนเงินเมื่อล้มเหลว:

• คำขอที่ถูกปฏิเสธ (พารามิเตอร์ผิด, 4xx/5xx ของแพลตฟอร์ม, ยอดเงินไม่พอเอง) ไม่คิดเงิน — เมื่อทดสอบส่งด้วยเสียงที่ไม่มีอยู่ ยอดเงินไม่เปลี่ยนเลย (delta = 0)
• งานที่ถูกรับแล้วแต่สุดท้ายล้มเหลว (รวมความผิดพลาดของบริการแพลตฟอร์ม) จะผ่านเส้นทางคืนเงินฝั่งเซิร์ฟเวอร์และคืนยอดที่หักล่วงหน้า

1.7 พจนานุกรมสถานะ

status ของเสียง:

status ของเพลง (ค่าที่เอนด์พอยต์สอบถามคืนมา):

2. ภาพรวมเอนด์พอยต์

3. สร้างเสียง

POST /api/music/voice-profile/create

ลงทะเบียนไฟล์เสียงร้องหนึ่งช่วงเป็น "เสียง" แล้วได้ voice_id สำหรับแพลตฟอร์ม เสียงคือ "ไฟล์เสียงหนึ่งไฟล์ + clip ของมันในคลัง" ดังนั้นเมื่อสร้างสำเร็จ ไฟล์เสียงต้นฉบับจะถูกเก็บถาวร (ใช้คัฟเวอร์ต่อไป)

3.1 รูปแบบอินพุตสามแบบ (เลือกหนึ่ง)

แบบ A: อัปโหลดไฟล์ multipart (แนะนำ)

Content-Type: multipart/form-data

file=<ข้อมูลไบนารีเสียง>      # จำเป็น
title=<ชื่อเสียง>              # ไม่บังคับ ถ้าว่างจะใช้ชื่อไฟล์ตัดนามสกุล
file_name=<ชื่อไฟล์เดิม>
source_file_name=<ชื่อไฟล์เดิม>
source_kind=upload|record     # ไม่บังคับ เครื่องหมายที่มา (อัปโหลด / อัดเสียง) ค่าเริ่มต้น upload
enhanced=false|true           # ไม่บังคับ true = โคลนแบบเสริม (ดู §3.5)
client_request_id=<คีย์กันซ้ำ>  # ไม่บังคับ
voice_id=<ID ที่กำหนดเอง>       # ไม่บังคับ ปกติไม่ใช้

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=เสียงของฉัน" \
  -F "source_kind=upload"

แบบ B: JSON + URL ไฟล์เสียงสาธารณะ

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "เสียงของฉัน"
      }'

• URL ต้องเป็นลิงก์ตรง HTTPS ที่เข้าถึงได้สาธารณะ เซิร์ฟเวอร์จะดาวน์โหลดหนึ่งครั้งและย้ายไปเก็บในออบเจกต์สตอเรจของเรา
• ใส่ที่อยู่ในฟิลด์ audio_url ก็ได้ ผลเท่ากัน (ถ้าส่งทั้งคู่จะใช้ file_url เป็นหลัก)
• ถ้าที่อยู่อยู่ในออบเจกต์สตอเรจของแพลตฟอร์มนี้อยู่แล้ว (*.myqcloud.com/create-ui/voice-source/...) จะไม่ดาวน์โหลดซ้ำ ลงทะเบียนตรง

แบบ C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "เสียงของฉัน"
}

• รองรับทั้งคำนำหน้า data:audio/xxx;base64, และ base64 ล้วน
• ขนาดจำกัด (base64 ขยาย 1.33 เท่า) ไฟล์ใหญ่ควรใช้แบบ A

3.2 ข้อกำหนดของไฟล์เสียง

3.3 คำตอบ

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "เสียงของฉัน",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

คำอธิบายฟิลด์ (create / list / detail ใช้ชุดฟิลด์เดียวกัน):

created_at / updated_at เป็นตราเวลาระดับวินาที (10 หลัก) ไม่ใช่มิลลิวินาที

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

3.5 โคลนแบบเสริม (enhanced=true)

ใช้กับกรณี "ตัวอย่างเสียงมีเนื้อเพลงที่มีลิขสิทธิ์ / ต้องอัปโหลดแบบเสริม" ราคาตามราคาอัปโหลดแบบเสริม (ค่าเริ่มต้น 10 หยวนต่อครั้ง ล้มเหลวคืนเงินอัตโนมัติ):

• คำตอบจะเป็น status=processing + task_id ทันที (ยังไม่มี clip_id) และทำงานแบบไม่รอผล
• ระหว่างประมวลผลใช้ GET /api/music/voice-profile/{voice_id} ดูความคืบหน้า จะคืน progress_percent / progress_stage / progress_message
• เมื่อเสร็จ status เป็น ready และ clip_id, audio_url, image_url จะถูกเติมให้
• ถ้าล้มเหลว status=failed และ error_message ประมาณว่า "อัปโหลดแบบเสริมล้มเหลว ค่าบริการถูกคืนอัตโนมัติ โปรดลองใหม่ภายหลัง"
• โคลนแบบเสริมใช้เวลานานกว่าการสร้างปกติอย่างชัดเจน (ระดับนาที) จึงไม่ควรใช้ตรรกะหมดเวลาแบบรอผล

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=เสียงของฉัน" -F "enhanced=true"

4. สร้างเสียงจากไฟล์เสียงที่มีอยู่

ถ้าไม่อยากอัปโหลดใหม่: คัดลอกไฟล์เสียงที่คุณอัปโหลดแล้วหรือสร้างแล้วมาเป็นเสียงได้เลย ฟรีและกันซ้ำ

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: clip id ของไฟล์เสียงที่เสร็จแล้วในบัญชีคุณ (เท่ากับ song_id ของเพลง)
• ส่ง clip เดิมซ้ำจะไม่สร้างรายการใหม่ คืนเสียงที่มีอยู่พร้อม reused: true (วัดผล)

คำตอบคือทุกฟิลด์ใน §3.3 บวกอีกสองฟิลด์แบบอ่านอย่างเดียว:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

ข้อผิดพลาด (message ตามต้นฉบับ แนะนำให้แสดงตรง ๆ หรือแปล):

5. รายการ / รายละเอียด / ลบเสียง

5.1 รายการ

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "เสียงของฉัน", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

ฟิลด์เหมือน §3.3 ทั้งหมด ค่าเริ่มต้นจะไม่คืนเสียงที่ถูกลบ

5.2 รายละเอียด

GET /api/music/voice-profile/{voice_id}

คืนออบเจกต์เสียงหนึ่งรายการ (data เป็นออบเจกต์เอง ไม่ใช่อาร์เรย์) เมื่อโคลนแบบเสริมกำลังทำงาน จะมีเพิ่ม:

5.3 ลบ

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• หลังลบ เสียงจะหายจากรายการและใช้คัฟเวอร์ใหม่ไม่ได้: ส่งด้วย voice_id นี้จะคืน 400 (ดู §6.4)
• เพลงที่สร้างด้วยเสียงนี้แล้วไม่ได้รับผลกระทบเลย การเล่น ดาวน์โหลด ต่อเพลง แทนที่ และแยกแทร็กยังทำงานปกติ
• ลบเสียงที่ไม่มีอยู่ หรือไม่ใช่ของบัญชีนี้ จะคืน {"success":false,"message":"voice not found"}

6. คัฟเวอร์ด้วยเสียง (เอนด์พอยต์หลัก)

POST /api/music/voice-profile/cover
Content-Type: application/json

หนึ่งครั้งสร้าง 2 เพลง (เหมือนการสร้างปกติ)

6.1 สองสถานการณ์

resolved_scene ในคำตอบจะสะท้อน cover หรือ sing เพื่อยืนยันว่าใช้เส้นทางไหน

6.2 ฟิลด์คำขอ

แนะนำให้ส่งเฮดเดอร์ X-Create-Ui-Client-Request-Id: <id การส่งเดียวกัน> ด้วย: มีแต่มันที่จะถูกเขียนลงบันทึกงานฝั่งเซิร์ฟเวอร์ และเป็นคีย์หลักในการตรวจสอบย้อนหลัง (ดู §1.5)

ข้อควรระวังหน่วย: audio_weight / style_weight / weirdness_constraint เป็นทศนิยม 0–1 variety เป็นจำนวนเต็ม 0–4 duration เป็นวินาที ถ้าใช้ปนกันจะถูกปฏิเสธหรือผลผิดปกติ

เนื้อเพลงในสถานการณ์ B ไม่บังคับ (โมเดลจัดการเอง) แต่ถ้าต้องการให้ร้องเนื้อหาที่กำหนดต้องส่ง lyrics

6.3 คำตอบ

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[งาน] นี่คือการคัฟเวอร์ … (ส่วนโครงสร้างคงที่ของเซิร์ฟเวอร์ + ความต้องการคัฟเวอร์ / สไตล์ที่คุณกรอก)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

จุดสำคัญ:

1. ระบุผลงานสำเร็จรูปด้วย clips[].song_id (เอนด์พอยต์นี้ไม่คืนฟิลด์ id)
2. ได้ song_id 2 รายการทันที แต่ตอนนั้น status ยังเป็น processing (แค่หมายถึงถูกรับแล้ว) และ audio_url ว่าง ต้องโพลถึง completed จึงดาวน์โหลดได้ play_url เป็นสตรีมฟังตัวอย่างของแพลตฟอร์ม อาจปรากฏตั้งแต่ขั้นส่ง และจะหมดอายุ
3. description คือพรอมป์ตที่เซิร์ฟเวอร์ส่งจริงครั้งสุดท้าย (ส่วนโครงสร้างคงที่ + cover_requirements / style_requirements ที่คุณกรอก) ใช้ตรวจสอบผลได้ดี
4. source_updates เป็นผลจัดการวัสดุของเซิร์ฟเวอร์ ไคลเอนต์ไม่ต้องสนใจ
5. title ที่คุณส่งจะถูกเขียนลงบันทึกงานฝั่งเซิร์ฟเวอร์ และแสดงเป็น song_title ในการสอบถามภายหลัง ส่วน clips[].song_title ในคำตอบตอนส่งมักว่าง เป็นเรื่องปกติ

6.4 ข้อผิดพลาด

{ "error": { "message": "เสียงนี้ไม่มีอยู่หรือถูกลบแล้ว (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

ยอดเงินไม่พอจะคืนข้อผิดพลาดการคิดเงินทันทีตอนส่ง และไม่ทิ้งงานค้างครึ่งทาง

6.5 โมเดลที่ใช้ได้ (ชื่อสำหรับลูกค้า)

ใช้ชื่อโมเดลสำหรับลูกค้า (ตามข้างบน) ส่วน chirp-* เป็นชื่อภายในของแพลตฟอร์ม ไม่ควรใช้ตรง ๆ

7. ติดตามความคืบหน้า

7.1 สอบถามแบบกลุ่ม (แนะนำ)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids เป็นสตริงคั่นด้วยเครื่องหมายจุลภาค (ไม่ใช่อาร์เรย์)
• คำตอบเป็นอาร์เรย์เปล่า (เริ่มด้วย [...] เลย ไม่มีเปลือก success / data):

[
  {
    "song_id": "0f2a…",
    "song_title": "เสือสองตัว",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[งาน] นี่คือการคัฟเวอร์ … (พรอมป์ตสุดท้ายของเซิร์ฟเวอร์)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

คำแนะนำการโพล: ทุก 5–10 วินาที หมดเวลารวม 10–15 นาที (บัญชี "เย็น" ที่ช้าที่สุดวัดได้ประมาณ 4 นาทีครึ่ง น้อยมากที่นานกว่า) อย่าตัดสินว่าเสร็จจาก audio_url ว่าง ให้ดู status

หมายเหตุความเข้ากันได้: เอนด์พอยต์นี้ใช้ song_id เป็นตัวระบุ ในคำตอบยุคแรกบางรายการมีฟิลด์ id จึงควรเขียนเป็น row.song_id || row.id

7.2 รายละเอียดเพลงเดียว

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "เสือสองตัว",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "เสือสองตัว",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• ตรงนี้ created_at / completed_at เป็นวินาทีแบบ Unix (ต่างจากสตริง ISO ของการสอบถามแบบกลุ่ม ไคลเอนต์ต้องแยกให้ออก)
• wav_url / video_url เป็นทางเข้าดาวน์โหลดของแพลตฟอร์มนี้ (อ้างอิงโดเมนปัจจุบัน) ใช้ GET รับไฟล์ได้ ถ้าแพลตฟอร์มยังไม่มีผลผลิตนั้นจะเป็นสตริงว่าง
• parameter_retention บอกว่าเพลงนี้สืบค้นพารามิเตอร์การส่งใดได้บ้าง: core_parameters_available=true หมายถึงเนื้อเพลง / สไตล์ / ต้นทาง ค้นได้ ส่วน extended_parameters_available=false หมายถึงพารามิเตอร์ขยายที่ระบุข้างบนไม่ถูกเก็บไว้ (คัฟเวอร์ด้วยเสียงจัดอยู่ในกลุ่มนี้)

7.3 ผลงานของฉัน

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=คำค้น

พารามิเตอร์แบ่งหน้า: p (เลขหน้า เริ่มที่ 1) / page_size (จำนวนต่อหน้า เขียนแบบเข้ากันได้คือ ps) เสริมได้ด้วย status และ q (คำค้นในชื่อเพลง) ค่าเริ่มต้นเรียงตามเวลาสร้างจากใหม่ไปเก่า

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "เสือสองตัว",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

ใช้ generation_type=voice_profile_cover แยก "เพลงที่เกิดจากคัฟเวอร์ด้วยเสียง" ออกจากผลการสร้างอื่นได้

8. ดาวน์โหลดผลงาน

8.1 เอา mp3 ตรง ๆ (แนะนำ ฟรี)

ทำได้ทั้งสามวิธี เลือกอย่างหนึ่ง:

1. ใช้ audio_url จากผลการสอบถาม (ลิงก์ตรงไปยังออบเจกต์สตอเรจ สะดวกที่สุด)
2. GET /api/music/download?song_id=<id>&kind=mp3 → คืนสตรีมไบต์เสียงโดยตรง (Content-Disposition มีชื่อไฟล์แล้ว)
3. POST /api/music/download-url (ขอที่อยู่ชั่วคราวแบบมีลายเซ็น)

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

ค่า kind: mp3 (เทียบเท่า song) / playback (เล่นแบบสตรีม) / wav / video / lyrics / timestamped_lyrics timestamped_lyrics (.lrc) ปัจจุบันรองรับเฉพาะบางเพลง ถ้าล้มเหลวให้ใช้ API เนื้อเพลงมีมาร์กเวลา สร้างเอง คำตอบเป็นสตรีมไบต์ของไฟล์ Content-Type และ Content-Disposition (ชื่อไฟล์) พร้อมแล้ว ส่วน wav_url / video_url ที่ GET /api/music/songs/{song_id} คืนมาคือทางเข้าเดียวกันแบบ kind=wav|video

8.2 แปลง wav / เนื้อเพลง / ข้อมูลเมตา (มีค่าใช้จ่าย)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files รองรับ: mp3 / wav / lyrics / metadata ครั้งละไม่เกิน 10 เพลง
• คิดค่าบริการตามจำนวนเพลงที่สำเร็จ (0.2 หยวนต่อเพลง) เพลงที่ล้มเหลวทั้งหมดไม่คิดเงิน และรูปแบบที่ล้มเหลวจะปรากฏใน songs[].errors
• ต้องการไฟล์ที่เคยโหลดไปแล้วอีกครั้ง ให้ใช้ ฟรี POST /api/music/free2/cached (ส่ง song_ids + files เดิม) เพื่อขอที่อยู่ที่เก็บถาวร โดย songs[].missing_files ในคำตอบจะบอกว่ารูปแบบใดไม่มีแคชและต้องจัดเตรียมใหม่

9. สอบถามราคา

GET /api/pricing/catalog

เอนด์พอยต์สาธารณะ ไม่ต้องยืนยันตัวตน ราคาต่อหน่วยที่ต้องแสดงต่อลูกค้าอยู่ใน data.catalog.meta (สตริง):

ราคาถูกปรับในหลังบ้าน ควรอ่านแบบเรียลไทม์ ไม่ควรเขียนตายในไคลเอนต์ ค่าบริการคัฟเวอร์จริง = voice_generation_price × (ถ้า max_mode เป็นจริงคูณ max_mode_factor อีก)

10. ข้อจำกัดและข้อควรระวัง

1. ขนาดอัปโหลด: ≤ 10MB (เซิร์ฟเวอร์รับได้มากกว่า แต่เกตเวย์ทางเข้าจะตัดเนื้อหาขนาดใหญ่ที่ 10MiB ทำให้ดูเหมือน "ถูก Suno ปฏิเสธ" จึงควรกันไว้ก่อนที่ฝั่งคุณ)
2. ความยาวตัวอย่าง: อย่างน้อย 6 วินาที แนะนำ 10–60 วินาที สั้นเกินไปแพลตฟอร์มจะปฏิเสธ
3. เนื้อหาตัวอย่าง: เสียงร้องสะอาด หลีกเลี่ยงสิ่งที่คล้ายบันทึกที่มีอยู่ (การเทียบกับคลังจะปฏิเสธ)
4. ขีดจำกัดข้อความ: lyrics ≤ 3000 ตัวอักษร แนะนำให้ style_requirements / negative_tags / title อยู่ใน 1000 / 1000 / 100 ตัวอักษรตามลำดับ (ความต้องการสไตล์และคัฟเวอร์จะถูกต่อเข้าไปในพรอมป์ต จึงควรรวมกันไม่เกิน 3000 ตัวอักษร)
5. เนื้อเพลงไม่ถูกดัดแปลง: ส่งอะไรก็ร้องอย่างนั้น (ตรงตัวอักษร) ไม่ตัดทอนในเครื่อง
6. แต่ละเพลงให้ 2 ผลงานเสมอ ไม่ควรคิดว่าจะได้เพลงเดียว
7. ไฟล์เสียงต้นฉบับเก็บถาวร: ลบเสียงก็ไม่ล้างไฟล์ต้นฉบับ เพื่อให้คัฟเวอร์ต่อไปใช้ได้และตรวจสอบความสอดคล้องได้
8. เสียงต้อง ready: เสียงที่ processing ใช้คัฟเวอร์ไม่ได้
9. เวลาหมดของคำขอ: บัญชี "เย็น" ส่งครั้งแรกช้าสุดที่วัดได้ประมาณ 4 นาทีครึ่ง ควรตั้งเวลาหมดของไคลเอนต์ ≥ 6 นาที คัฟเวอร์ไม่ตัดข้อมูลซ้ำระดับคำขอ หลังหมดเวลาให้ตรวจก่อนว่ามีเพลงใหม่เกิดแล้วหรือยัง (§1.5) จึงตัดสินใจส่งซ้ำ
10. ความเป็นเจ้าของเสียง: เสียงเป็นของผูสร้าง คัฟเวอร์รับเฉพาะเสียงที่พร้อมและไม่ถูกลบ ถ้าไม่มีอยู่ ถูกลบ หรือไม่ใช่ของบัญชีนี้ จะคืน 400: เสียงนี้ไม่มีอยู่หรือถูกลบแล้ว (voice_id=…)

11. คำถามที่พบบ่อย (FAQ)

ถาม 1. สร้างเสียงมีค่าใช้จ่ายไหม? การสร้างปกติและ "สร้างจากไฟล์เสียงที่มีอยู่" ฟรี มีค่าใช้จ่ายเฉพาะคัฟเวอร์ (1.2 หยวน / MAX 2.4 หยวน) และโคลนแบบเสริม (ค่าเริ่มต้น 10 หยวน)

ถาม 2. ใช้เพลงสำเร็จรูปที่มีดนตรีประกอบเป็นตัวอย่างเสียงได้ไหม? ไม่แนะนำ สิ่งที่มีดนตรีหรือคล้ายบันทึกในคลังมากจะถูกแพลตฟอร์มปฏิเสธ (This audio matches an existing recording in our catalog.) ควรใช้เสียงร้องล้วนแบบแห้ง

ถาม 3. ทำไมส่งคัฟเวอร์แล้ว audio_url ว่าง? การส่งหมายถึงถูกรับแล้วเท่านั้น status ยังเป็น processing ต้องโพล /api/music/query ถึง status=completed จึงจะมีที่อยู่เล่น/ดาวน์โหลดได้

ถาม 4. สถานการณ์ B (ไม่ส่ง song_clip_id) ต้องส่งเนื้อเพลงไหม? ไม่บังคับ ถ้าต้องการให้ร้องเนื้อหาที่กำหนดให้ส่ง lyrics ถ้าไม่ส่งโมเดลจัดการเอง แต่ควบคุมได้น้อยกว่า

ถาม 5. ไฟล์เสียงที่ลูกค้าอัปโหลดเองใช้เป็นเสียงได้เลยไหม? ได้ ผ่านรูปแบบ file_url ของ create หรืออัปโหลดเป็นเพลงก่อนแล้วเรียก create-from-clip

ถาม 6. ล้มเหลวแล้วคืนเงินไหม? คำขอที่ถูกปฏิเสธทันที (พารามิเตอร์ผิด / แพลตฟอร์มแจ้งข้อผิดพลาด) ไม่คิดเงิน ตามผลวัด ส่วนงานที่ถูกรับแล้วแต่สุดท้ายล้มเหลวจะคืนยอดที่หักล่วงหน้า เมื่อล้มเหลวขั้นสุดท้าย งานจะคืน status=failed และ error_message

ถาม 7. ลบเสียงแล้วเพลงที่เคยสร้างด้วยเสียงนั้นยังฟังได้ไหม? ได้ การลบมีผลเฉพาะว่าเสียงนั้นจะใช้คัฟเวอร์ใหม่ได้หรือไม่

ถาม 8. คัฟเวอร์ได้ยาวเท่าไรต่อครั้ง? duration ส่ง 1–480 วินาที ถ้าไม่ส่งแพลตฟอร์มจะกำหนดจากเพลงต้นฉบับ / วัสดุ ระวังผลงานสำเร็จรูปของแพลตฟอร์มสั้นสุดประมาณ 30 วินาที: ใส่ค่าน้อยกว่า 30 วินาที ผลวัดยังได้ 29.96 / 29.76 วินาที

ภาคผนวก A: ตัวอย่างการเรียกครบชุด (Node.js มีการโพลและดาวน์โหลด)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① สร้างเสียง (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② คัฟเวอร์
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "โฟล์กช้า ๆ กีตาร์อะคูสติก",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ โพลจนเสร็จ (ทุก 5 วินาที สูงสุด 15 นาที)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // อาร์เรย์เปล่า
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ ดาวน์โหลด
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "เสียงของฉัน");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nเนื้อเพลง…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

ภาคผนวก B: บันทึกการเปลี่ยนแปลง