API สอบถามเพลงและประวัติ
หน้านี้ครอบคลุมเอนด์พอยต์สอบถามฟรีสามตัว:
| ความสามารถ | Method | เอนด์พอยต์ |
|---|---|---|
| สอบถามสถานะและผลลัพธ์ของเพลงหนึ่งเพลง | POST | /api/music/query |
| สอบถามเพลงที่บัญชีปัจจุบันสร้างไว้ | GET | /api/music/songs |
| สอบถามพารามิเตอร์ที่บันทึกไว้ตอนสร้างเพลง | GET | /api/music/songs/:song_id |
ถ้าคุณใช้ โหมดใบรับคำสั่ง (
accept_mode=async) กับเอนด์พอยต์สร้างเพลง สิ่งที่คุณถืออยู่คือเลขใบรับคำสั่ง ไม่ใช่ ID เพลง ให้ติดตามความคืบหน้าด้วยGET /api/music/requests/{request_id}แล้วกลับมาที่เอนด์พอยต์ในหน้านี้ เมื่อได้song_idจริงแล้ว ให้ดูหัวข้อ "โหมดใบรับคำสั่ง" ใน API สร้างเพลงโหมดง่าย
การยืนยันตัวตนและขอบเขตข้อมูล
ทั้งสามเอนด์พอยต์ใช้คีย์ API เดียวกัน:
Authorization: Bearer YOUR_API_KEY
ประวัติเพลงแยกตาม user_id ที่คีย์ API สังกัดอยู่ คีย์หลายตัวที่สร้างภายใต้บัญชีหลักเดียวกันสามารถอ่านประวัติของบัญชีนั้นได้ แต่ไม่สามารถอ่านเพลงของผู้ใช้รายอื่นหรือบัญชีเว็บย่อยอื่นได้
เอนด์พอยต์ประวัติคืนเฉพาะเพลงที่สร้างจริงเท่านั้น ไม่รวม:
- เรกคอร์ดตัวแทนชั่วคราวของการสร้างที่ขึ้นต้นด้วย
pending:; - การอัปโหลดเสียงต้นทางและเรกคอร์ดการอัปโหลดแบบเสริม;
- ผลลัพธ์ย่อย เช่น การแยกเสียงร้อง/ดนตรี และสเต็ม;
- เพลงของผู้ใช้รายอื่นหรือบัญชีเว็บย่อยอื่น
1. สอบถามสถานะการสร้าง
ใช้ค้นสถานะปัจจุบันและผลลัพธ์สุดท้ายจาก ID เพลงหนึ่งหรือหลายเพลง
เอนด์พอยต์: POST /api/music/query
ค่าบริการ: ฟรี
Headers
| พารามิเตอร์ | ชนิด | จำเป็น | หมายเหตุ |
|---|---|---|---|
| Authorization | string | ใช่ | Bearer YOUR_API_KEY |
| Content-Type | string | ใช่ | application/json |
พารามิเตอร์บอดี
| พารามิเตอร์ | ชนิด | จำเป็น | ค่าเริ่มต้น | หมายเหตุ |
|---|---|---|---|---|
| model | string | ไม่ | suno-v6 |
เวอร์ชันโมเดล |
| song_ids | string | ใช่ | - | ID เพลง หลายตัวคั่นด้วยเครื่องหมายจุลภาค |
ตัวอย่างคำขอ
curl -X POST https://www.suno-api.io/api/music/query \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"song_ids": "clip_id_1,clip_id_2"
}'
ตัวอย่างคำตอบ
[
{
"song_id": "clip_id_1",
"song_title": "ชื่อเพลง",
"status": "completed",
"audio_url": "https://example.com/audio.mp3",
"video_url": "https://example.com/video.mp4",
"cover_url": "https://example.com/cover.jpg",
"lyrics": "เนื้อเพลง",
"style_tags": "Mandopop, acoustic",
"duration": 180.5,
"model_version": "suno-v6",
"created_at": "2026-05-21T10:00:00Z"
}
]
หมายเหตุเรื่องความเข้ากันได้
เอกสารรุ่นเก่าอาจแสดง song_ids เป็นอาร์เรย์ ปัจจุบันแนะนำให้ใช้สตริงที่คั่นด้วยจุลภาค ซึ่งตรงกับวิธีเรียกเอนด์พอยต์จริง
song_ids ต้องเป็น ID เพลงจริง ID ตัวแทนชั่วคราวที่ขึ้นต้นด้วย pending: ไม่ใช่ song_id สุดท้ายและใช้ที่นี่ไม่ได้ หากสอบถามเฉพาะ ID ตัวแทนชั่วคราวอาจได้อาร์เรย์ว่าง []
ค่า model, model_version หรือ model_name ของแพลตฟอร์มในคำตอบอาจเป็นค่าในอดีต งานใหม่ควรใช้ suno-v6, suno-v6-wild หรือ suno-v6-mini ส่วน suno-v2 ถึง suno-v5-5 ยกเลิกแล้ว และการเห็นชื่อเหล่านี้ในประวัติไม่ได้หมายความว่ายังส่งโมเดลนั้นได้
ระหว่างที่งานอยู่ในสถานะ pending, submitted หรือ processing ค่า audio_url, video_url และ cover_url อาจว่างได้ ซึ่งเป็นเรื่องปกติของงานที่ยังไม่เสร็จ อย่าตัดสินว่าล้มเหลวจากที่อยู่ที่ว่างเพียงอย่างเดียว ให้ดู status ประกอบและสอบถามอีกครั้งเมื่อสถานะเสร็จสมบูรณ์ จะแนะนำให้ติดต่อฝ่ายสนับสนุนพร้อม song_id ก็ต่อเมื่อสถานะเสร็จแล้วแต่ที่อยู่ยังว่างอยู่
⚠️ ที่อยู่ไฟล์เสียงมีอายุ 7 วัน — โอนไฟล์ของคุณให้ทันเวลา
audio_url,video_url(และที่อยู่สื่ออื่น ๆ เช่น WAV) ที่คืนจากที่นี่ให้บริการจากที่เก็บออบเจ็กต์ของแพลตฟอร์ม และ หมดอายุใน 7 วันเป็นค่าเริ่มต้น: ไฟล์จะถูกเก็บคืน ที่อยู่เก่าจะคืน 404
- ภายใน 7 วันนั้น ให้ย้ายไฟล์ไปยังที่เก็บของคุณเอง อย่าถือว่าที่อย่านี้เป็นลิงก์อายุยาว
- ที่อยู่ที่หมดอายุ ไม่ต้องสร้างเพลงใหม่และไม่มีค่าใช้จ่ายเพิ่ม: เรียกเอนด์พอยต์นี้ (
POST /api/music/query) อีกครั้งเพื่อรับ ที่อยู่ใหม่ที่ยังใช้ได้ ของเพลงนั้น
2. สอบถามประวัติเพลงของบัญชี
แสดงรายการเพลงที่บัญชีหลักของคีย์ API ปัจจุบันสร้างไว้ เหมาะกับการสร้างรายการเพลง ตัวเลือก หรือหน้าประวัติของคุณเอง
เอนด์พอยต์: GET /api/music/songs
ค่าบริการ: ฟรี
พารามิเตอร์คำค้น
| พารามิเตอร์ | ชนิด | จำเป็น | ค่าเริ่มต้น | หมายเหตุ |
|---|---|---|---|---|
| p | integer | ไม่ | 1 |
หมายเลขหน้า เริ่มที่ 1 |
| page_size | integer | ไม่ | 20 |
จำนวนต่อหน้า สูงสุด 100 |
| q | string | ไม่ | - | ค้นหาแบบใกล้เคียงตามชื่อเพลง หรือค้นหาแบบตรงตาม ID เพลงเต็ม |
| status | string | ไม่ | - | กรองสถานะแบบตรง เช่น completed, playable |
ผลลัพธ์เรียงจาก created_at และ ID เรกคอร์ดภายในจากมากไปน้อย ลำดับการแบ่งหน้าจึงคงที่
วิธีตามหางานที่ส่งแล้วหมดเวลา: เอนด์พอยต์สร้างเพลงไม่มีการตอบกลับระหว่างทางก่อนการรับคำสั่ง หากไคลเอนต์หมดเวลาหรือการเชื่อมต่อขาดตอนที่ส่ง คำสั่งนั้นอาจถูกรับไว้และกำลังสร้างแล้ว ลองดูเอนด์พอยต์นี้ (ใหม่สุดก่อน): เพลงที่ถูกรับไว้จะปรากฏในรายการตามปกติ ส่งซ้ำก็ต่อเมื่อยืนยันแล้วว่าไม่มีจริง เพื่อไม่ให้จ่ายซ้ำ ดูหัวข้อ "ระยะเวลารอและการตั้งค่า timeout" ใน ภาพรวม API ใหม่
ตัวอย่างคำขอ
curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
-H "Authorization: Bearer YOUR_API_KEY"
ตัวอย่างคำตอบ
{
"success": true,
"message": "",
"data": {
"page": 1,
"page_size": 20,
"total": 42,
"items": [
{
"song_id": "8e31b3c0-example-song-id",
"title": "เมืองในยามค่ำคืน",
"status": "completed",
"generation_type": "custom_generate",
"model": "suno-v6",
"duration": 187.42,
"audio_url": "https://example.com/audio.mp3",
"image_url": "https://example.com/cover.jpg",
"created_at": 1784000000,
"completed_at": 1784000120
}
]
}
}
ฟิลด์ที่คืนกลับ
| ฟิลด์ | ชนิด | หมายเหตุ |
|---|---|---|
| song_id | string | ID เพลงจริง ใช้สอบถามรายละเอียดได้ |
| title | string | ชื่อปัจจุบัน ซึ่งผู้ใช้อาจเปลี่ยนแล้ว |
| status | string | สถานะปัจจุบัน |
| generation_type | string | ประเภทการสร้าง |
| model | string | โมเดลที่ใช้สร้าง |
| duration | number | ความยาวเสียงเป็นวินาที |
| audio_url | string | ที่อยู่ไฟล์เสียง อาจว่างเมื่อยังไม่เสร็จ |
| image_url | string | ที่อยู่ภาพปก อาจว่างได้ |
| created_at | integer | เวลาสร้าง เป็น Unix timestamp หน่วยวินาที |
| completed_at | integer | เวลาสำเร็จ เป็น Unix timestamp หน่วยวินาที อาจไม่คืนเมื่อยังไม่เสร็จ |
เอนด์พอยต์รายการไม่คืนพรอมป์ต์ ฟิลด์ค่าบริการ ข้อมูลบัญชี หรือคำตอบดิบ หากต้องการพรอมป์ต์และพารามิเตอร์การสร้าง ให้เรียกเอนด์พอยต์รายละเอียดเพลง
3. สอบถามพารามิเตอร์การสร้าง
ค้นพรอมป์ต์ สไตล์ โมเดล และเพลงต้นทางที่แพลตฟอร์มบันทึกไว้ตอนสร้างเพลงนั้น
เอนด์พอยต์: GET /api/music/songs/:song_id
ค่าบริการ: ฟรี
อ่านได้เฉพาะเพลงของบัญชีหลักที่คีย์ API ปัจจุบันสังกัดอยู่ เพลงของผู้ใช้รายอื่นหรือบัญชีเว็บย่อยอื่นจะถูกจัดการเป็น "ไม่พบเพลง" เสมอ
พารามิเตอร์ในเส้นทาง
| พารามิเตอร์ | ชนิด | จำเป็น | หมายเหตุ |
|---|---|---|---|
| song_id | string | ใช่ | ID เพลงจริง |
ตัวอย่างคำขอ
curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
-H "Authorization: Bearer YOUR_API_KEY"
ตัวอย่างคำตอบ
{
"success": true,
"message": "",
"data": {
"song_id": "8e31b3c0-example-song-id",
"title": "เมืองในยามค่ำคืน",
"status": "completed",
"generation_type": "custom_generate",
"model": "suno-v6",
"duration": 187.42,
"audio_url": "https://example.com/audio.mp3",
"image_url": "https://example.com/cover.jpg",
"video_url": "",
"wav_url": "",
"created_at": 1784000000,
"completed_at": 1784000120,
"client_request_id": "example-request-id",
"client_request_index": 0,
"parameters": {
"prompt": "ถนนในเมืองหลังฝนตก เนื้อเพลงเกี่ยวกับการกลับมาพบกัน",
"style_tags": "Mandopop, acoustic, warm vocal",
"title": "เมืองในยามค่ำคืน",
"model": "suno-v6",
"generation_type": "custom_generate",
"source_song_id": "",
"source_audio_url": "",
"custom_mode": null,
"instrumental": null,
"negative_tags": null,
"vocal_gender": null,
"lyrics_mode": null,
"wait_audio": null,
"style_weight": null,
"weirdness_constraint": null
},
"parameter_retention": {
"core_parameters_available": true,
"extended_parameters_available": false,
"sources": [
"suno_tasks"
],
"unavailable_fields": [
"custom_mode",
"instrumental",
"negative_tags",
"vocal_gender",
"lyrics_mode",
"wait_audio",
"style_weight",
"weirdness_constraint"
]
}
}
}
ฟิลด์ parameters
| ฟิลด์ | ชนิด | หมายเหตุ |
|---|---|---|
| prompt | string | พรอมป์ต์สร้างเพลงหรือเนื้อเพลง |
| style_tags | string | แท็กสไตล์ |
| title | string | ชื่อเพลงที่บันทึกไว้ งานประวัติทั่วไปอาจเก็บไว้เพียงชื่อปัจจุบัน |
| model | string | โมเดลที่ใช้สร้าง |
| generation_type | string | ประเภทการสร้าง |
| source_song_id | string | ID เพลงต้นทางของงานคัฟเวอร์ ต่อเพลง และงานทำนองเดียวกัน |
| source_audio_url | string | ที่อยู่ไฟล์เสียงต้นทาง |
| custom_mode | boolean/null | ใช้โหมดกำหนดเองหรือไม่; null เมื่อไม่ได้บันทึก |
| instrumental | boolean/null | เป็นเพลงบรรเลงหรือไม่; ข้อมูลประวัติที่มีอยู่มักไม่บันทึกแยก |
| negative_tags | string/null | สไตล์ที่ตัดออก |
| vocal_gender | string/null | การตั้งค่าเพศเสียงร้อง |
| lyrics_mode | string/null | โหมดเนื้อเพลง; ข้อมูลประวัติที่มีอยู่มักไม่บันทึก |
| wait_audio | boolean/null | รอไฟล์เสียงเต็มหรือไม่; ข้อมูลประวัติที่มีอยู่มักไม่บันทึก |
| style_weight | number/null | น้ำหนักสไตล์ |
| weirdness_constraint | number/null | พารามิเตอร์ความสร้างสรรค์/ความแปลก |
ฟิลด์ prompt_view (ดูพรอมป์ต์ เพิ่มเมื่อ 2026-09-28)
prompt_view เป็นโครงสร้าง ที่ปรับให้เป็นมาตรฐาน สำหรับ "ดูพรอมป์ต์" โดยเฉพาะ: จัดข้อมูลเป็นส่วนคงที่
ตามประเภทการสร้าง ไคลเอนต์จึงไม่ต้องตัดสินใจเองว่าจะแสดงฟิลด์ใด เป็นฟิลด์
ที่เพิ่มเข้ามาเท่านั้น — ฟิลด์เดิม (parameters, parameter_retention) คงชื่อและ
ความหมายเดิม และไคลเอนต์ที่ไม่แยกวิเคราะห์ฟิลด์ใหม่จะไม่ได้รับผลกระทบใด ๆ
"prompt_view": {
"type": "custom_generate",
"type_label": "โหมดกำหนดเอง",
"generation": {
"model": "suno-v6", "max_mode": false, "duration": 182.4,
"title": "ตีสี่#701f37", "title_base": "ตีสี่", "title_suffix": "701f37",
"created_at": 1790421721
},
"inputs": {
"user_text": "...", "user_text_kind": "lyrics",
"user_style": "อิเล็กทรอนิกส์กั๋วเฉา, เบสลึก, ซินธ์เรโทร",
"style_tags": "อิเล็กทรอนิกส์กั๋วเฉา, เบสลึก, ซินธ์เรโทร",
"style_source": "user", "lyrics": "...",
"negative_tags": "", "is_instrumental": false
},
"extended": {
"vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
"weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
"custom_mode": true
},
"reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
"retention": {
"recorded_since": "2026-09-28", "missing_reason": "",
"not_applicable_fields": ["audio_weight"]
}
}
| ฟิลด์ | ชนิด | หมายเหตุ |
|---|---|---|
type / type_label |
string | ประเภทการสร้างดิบ / ป้ายที่แสดง (สร้างแบบง่าย, โหมดกำหนดเอง, โหมดเอฟเฟกต์เสียง, สร้างด้วยเสียงโคลน…) |
generation.model |
string | โมเดลที่ใช้ |
generation.max_mode |
bool | เปิด Max Mode หรือไม่ |
generation.duration |
number | ความยาวเสียง (วินาที) |
generation.title |
string | ชื่อตามที่บันทึกไว้ (อาจมีส่วนต่อท้าย) |
generation.title_base |
string | ชื่อที่แสดงโดยตัดส่วนต่อท้าย #xxxxxx ออก |
generation.title_suffix |
string | ส่วนต่อท้าย (ไม่รวม #); ว่างเมื่อไม่มี |
inputs.user_text |
string | ข้อมูลที่ผู้ใช้ป้อน (คำอธิบายหรือเนื้อเพลง ตามประเภท) |
inputs.user_text_kind |
string | lyrics / description / cover_requirements |
inputs.user_style |
string | สไตล์ ที่ผู้ใช้กรอกเอง (โหมดกำหนดเอง, เสียง, เอฟเฟกต์เสียง) |
inputs.style_tags |
string | สไตล์ที่มีผลจริง |
inputs.style_source |
string | user = ผู้ใช้กรอก; suno_derived = Suno สรุปจากคำอธิบาย |
inputs.lyrics |
string | เนื้อเพลง; ว่างเมื่อไม่มี เพลงบรรเลงเป็น [Instrumental] |
inputs.negative_tags |
string | สไตล์ที่ตัดออก |
inputs.is_instrumental |
bool | เป็นเพลงบรรเลงหรือไม่ |
extended.* |
— | พารามิเตอร์ส่วนขยาย ดูด้านล่าง; ฟิลด์ที่ไม่ได้บันทึกจะไม่ปรากฏ |
reference.voice_name |
string | ชื่อเสียง (มีเฉพาะประเภทเสียง; persona id ภายใน ไม่ คืนกลับ) |
reference.source_song_id / source_title |
string | เพลงต้นทางของงานคัฟเวอร์ ต่อเพลง และงานทำนองเดียวกัน |
retention.recorded_since |
string | วันที่เริ่มบันทึกพารามิเตอร์ส่วนขยาย (2026-09-28) |
retention.missing_reason |
string | เหตุที่ไม่มีพารามิเตอร์ส่วนขยาย; ข้อมูลประวัติเป็น not_recorded_before_20260928 |
retention.not_applicable_fields |
string[] | พารามิเตอร์ที่ประเภทการสร้างนั้นไม่เคยต้องใช้ (ห้าม แสดงเป็น "พารามิเตอร์ขาด") |
ฟิลด์ที่อาจปรากฏใน extended: vocal_gender, style_weight, audio_weight,
weirdness_constraint, variety, lyrics_mode, custom_mode และกลุ่มเอฟเฟกต์เสียง
sound_type / sound_bpm / sound_key / sound_loop ค่าว่างจะไม่ถูกคืนเสมอ
กฎการแสดงผลสามข้อ (ทำตามนี้ ไม่ต้องคาดเดาเอง):
- แยกที่มาของสไตล์: เมื่อ
style_source=suno_derivedให้แสดงเป็น "สไตล์ (Suno สรุปจากคำอธิบายของคุณ)" ห้ามเขียนว่า "สไตล์ที่คุณกรอก"; - พรอมป์ต์ภายในจะไม่ปรากฏ: ประเภทคัฟเวอร์ด้วยเสียงจะคืนเฉพาะ 【ข้อกำหนดสไตล์】/【ข้อกำหนดการคัฟเวอร์】 ที่ผู้ใช้กรอก; โครงสร้างคงที่ที่เราประกอบให้โมเดลจะไม่ปรากฏในฟิลด์ใดเลย (ข้อมูลประวัติก็ถูกทำให้ปลอดภัยเช่นกัน);
- อย่าเดาพารามิเตอร์ที่ไม่ได้บันทึก: ถ้าไม่มีใน
extendedแสดงว่าตอนนั้นไม่ได้บันทึก ให้ใช้retentionอธิบายเหตุผล
หมายเหตุเรื่องการเก็บพารามิเตอร์
parameter_retention ใช้แยก "ส่งค่าว่างมาอย่างชัดเจน" ออกจาก "ไม่เคยบันทึกฟิลด์นี้ในอดีต":
core_parameters_available: มีเรกคอร์ดงานเพลงหลักหรือไม่ ปกติเป็นtrueสำหรับรายละเอียดที่ถูกต้อง;extended_parameters_available: พบเรกคอร์ดงานเพลงส่วนขยายที่เกี่ยวข้องหรือไม่;sources: คำตอบนี้มาจากตารางข้อมูลใด;unavailable_fields: ฟิลด์ที่กู้คืนจากข้อมูลประวัติได้ไม่น่าเชื่อถือ ฟิลด์เหล่านี้จะคืนnullในparameters
เพลงประวัติทั่วไปมักบันทึกพรอมป์ต์ สไตล์ ชื่อปัจจุบัน โมเดล ประเภทการสร้าง และเพลงต้นทาง แต่ไม่ได้บันทึกพารามิเตอร์ขั้นสูงทั้งหมดแยกไว้ แพลตฟอร์มไม่เดาค่าที่หายไปจาก generation_type เด็ดขาด
งานเพลงส่วนขยายบางงานยังบันทึกพรอมป์ต์ต้นฉบับ สไตล์ ชื่อ โมเดล และ custom_mode, negative_tags, vocal_gender, style_weight, weirdness_constraint ด้วย แม้มีเรกคอร์ดส่วนขยาย instrumental, lyrics_mode และ wait_audio ก็อาจยังกู้คืนไม่ได้
ชื่อเพลงผู้ใช้เปลี่ยนได้ในภายหลัง หากงานประวัติทั่วไปไม่ได้เก็บชื่อต้นฉบับแยกไว้ parameters.title อาจเป็นชื่อปัจจุบัน เมื่อมีเรกคอร์ดงานส่วนขยาย ระบบจะให้ความสำคัญกับชื่อการสร้างต้นฉบับที่บันทึกไว้ที่นั่น
ไม่พบหรือไม่มีสิทธิ์
ข้อผิดพลาดเชิงธุรกิจใช้ซองคำตอบเดียวกัน เมื่อเพลงไม่มีหรือไม่ใช่ของบัญชีปัจจุบัน จะคืน:
{
"success": false,
"message": "song not found"
}
ข้อผิดพลาดเชิงธุรกิจนี้ปัจจุบันคืน HTTP 200 จึงให้ตัดสินผลจากฟิลด์ success ส่วนคีย์ API ที่ขาด ไม่ถูกต้อง หมดอายุ หรือถูกปิดใช้งานจะคืน HTTP 401
หมายเหตุด้านความปลอดภัย
เอนด์พอยต์ประวัติและรายละเอียดจะไม่คืน:
- คีย์ API หรือ Token ID;
- ฟิลด์โควตา ค่าบริการ หรือการคืนเงิน;
- ข้อมูลบัญชีและคำตอบดิบ;
- คีย์ภายในของที่เก็บออบเจ็กต์;
- ข้อผิดพลาดของผู้ดูแลระบบและข้อผิดพลาดทรัพยากรภายใน
รับคีย์ API
สร้างคีย์ API ในคอนโซลหลังสมัครสมาชิก การสร้างหนึ่งครั้งราคา 0.6 หยวน ได้ 2 เพลง ดาวน์โหลดไม่จำกัด และไม่ต้องใช้เบอร์โทรศัพท์
รับคีย์ API กลับไปภาพรวม