API สอบถามเพลงและประวัติ

อัปเดต 2026-09-18 · ทีม Suno-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 สังกัดอยู่ คีย์หลายตัวที่สร้างภายใต้บัญชีหลักเดียวกันสามารถอ่านประวัติของบัญชีนั้นได้ แต่ไม่สามารถอ่านเพลงของผู้ใช้รายอื่นหรือบัญชีเว็บย่อยอื่นได้

เอนด์พอยต์ประวัติคืนเฉพาะเพลงที่สร้างจริงเท่านั้น ไม่รวม:


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 ค่าว่างจะไม่ถูกคืนเสมอ

กฎการแสดงผลสามข้อ (ทำตามนี้ ไม่ต้องคาดเดาเอง):

  1. แยกที่มาของสไตล์: เมื่อ style_source=suno_derived ให้แสดงเป็น "สไตล์ (Suno สรุปจากคำอธิบายของคุณ)" ห้ามเขียนว่า "สไตล์ที่คุณกรอก";
  2. พรอมป์ต์ภายในจะไม่ปรากฏ: ประเภทคัฟเวอร์ด้วยเสียงจะคืนเฉพาะ 【ข้อกำหนดสไตล์】/【ข้อกำหนดการคัฟเวอร์】 ที่ผู้ใช้กรอก; โครงสร้างคงที่ที่เราประกอบให้โมเดลจะไม่ปรากฏในฟิลด์ใดเลย (ข้อมูลประวัติก็ถูกทำให้ปลอดภัยเช่นกัน);
  3. อย่าเดาพารามิเตอร์ที่ไม่ได้บันทึก: ถ้าไม่มีใน extended แสดงว่าตอนนั้นไม่ได้บันทึก ให้ใช้ retention อธิบายเหตุผล

หมายเหตุเรื่องการเก็บพารามิเตอร์

parameter_retention ใช้แยก "ส่งค่าว่างมาอย่างชัดเจน" ออกจาก "ไม่เคยบันทึกฟิลด์นี้ในอดีต":

เพลงประวัติทั่วไปมักบันทึกพรอมป์ต์ สไตล์ ชื่อปัจจุบัน โมเดล ประเภทการสร้าง และเพลงต้นทาง แต่ไม่ได้บันทึกพารามิเตอร์ขั้นสูงทั้งหมดแยกไว้ แพลตฟอร์มไม่เดาค่าที่หายไปจาก 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 เนื้อเพลงพร้อมไทม์สแตมป์

รับคีย์ API

สร้างคีย์ API ในคอนโซลหลังสมัครสมาชิก การสร้างหนึ่งครั้งราคา 0.6 หยวน ได้ 2 เพลง ดาวน์โหลดไม่จำกัด และไม่ต้องใช้เบอร์โทรศัพท์

รับคีย์ API กลับไปภาพรวม