API เนื้อเพลงพร้อมไทม์สแตมป์

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

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

เนื้อเพลงพร้อมไทม์สแตมป์ใช้ดึงเวลาระดับคำของเพลง เพื่อแสดงเนื้อเพลงแบบซิงโครไนซ์

เอนด์พอยต์: POST /api/lyrics/timeline

ค่าบริการ: ฟรี (การสอบถามแบบอ่านอย่างเดียว ไม่คิดค่าใช้จ่ายและไม่สร้างงานสร้างเพลง)

รูปแบบการคืนค่า: คืนอาร์เรย์ไทม์ไลน์โดยตรง — ไม่มีชั้นห่อ data / success เมื่อแยกวิเคราะห์แล้วจะเป็นอาร์เรย์ทันที

พารามิเตอร์คำขอ

Headers

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

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

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_id": "clip_id"
  }'

คำตอบ

ด้านล่างเป็นคำตอบจริงจากระบบโปรดักชันของเพลงความยาว 189.6 วินาทีใน suno-v6 (ครั้งนั้นมีทั้งหมด 69 ท่อน ที่นี่เก็บไว้เฉพาะช่วงต้นและช่วงท้าย):

[
  {
    "word": "[Intro]\n\n\n[",
    "start_s": 15,
    "end_s": 15.04277,
    "success": true,
    "p_align": 0.99
  },
  {
    "word": "Instrumental: ",
    "start_s": 15.04704,
    "end_s": 15.10264,
    "success": true,
    "p_align": 0.99
  },
  {
    "word": "End]\n\n\n",
    "start_s": 189.16974,
    "end_s": 189.654,
    "success": true,
    "p_align": 0.99
  }
]

คำอธิบายฟิลด์

ข้อควรระวังในการใช้งาน

1. อย่าหาชั้นห่อ คำตอบคืออาร์เรย์เอง ไม่ใช่ {"data": ...} และไม่มีฟิลด์ success ด้วย
2. ช่วงต้นอาจไม่มีท่อนใดเลย เพลงที่มีเฉพาะดนตรีนำ จากการวัดพบว่าท่อนแรกเพิ่งปรากฏที่วินาทีที่ 15 และ start_s ไม่รับประกันว่าจะเริ่มจาก 0 หากทำคาราโอเกะต้องจัดการช่วงว่างตอนต้นเอง
3. เครื่องหมายดนตรีและโครงสร้างก็ถูกคืนมาด้วย ในรูปแบบ [Intro], [Verse 1], Instrumental: soft arpeggiating piano, …, [End] และให้เวลาแบบรายคำเช่นกัน ก่อนทำซับไตเติลเนื้อเพลงควรกรองท่อนเหล่านี้ออกด้วย [ ที่ขึ้นต้นหรือคำว่า Instrumental มิฉะนั้นคำอธิบายการเรียบเรียงจะถูกแสดงเป็นเนื้อเพลง
4. เป็นระดับคำ ไม่ใช่ระดับบรรทัด เนื้อเพลงบรรทัดเดียวกันมักถูกแบ่งเป็นหลายท่อน ต้องรวมเป็นบรรทัดด้วย \n และเวลาของบรรทัดใช้ start_s ของท่อนแรกในบรรทัดนั้น
5. จำนวนท่อนขึ้นอยู่กับเพลง อย่าสันนิษฐานจำนวนท่อนคงที่ (จากการวัด เพลง 189.6 วินาทีมี 69 ท่อน เนื้อคำตอบประมาณ 6.5 KB)

การสร้างไฟล์ .lrc

เอนด์พอยต์นี้คืนเฉพาะข้อมูลไทม์ไลน์ ไม่ได้คืนไฟล์โดยตรง หากต้องการ .lrc ให้ใช้ start_s ที่ได้มาต่อบรรทัดในรูปแบบ [mm:ss.cc] (ฟิลด์ word มีอักขระขึ้นบรรทัดใหม่ในตัว ให้แยกตามบรรทัดและข้ามบรรทัดว่าง) ตัวอย่างดูได้ในหัวข้อ "วิธีดึงเนื้อเพลงพร้อมไทม์สแตมป์ (.lrc)" ของ API ดาวน์โหลดและฟังตัวอย่างสื่อของเพลง

ด้านล่างเป็นตัวอย่างแบบเต็มที่มีการกรองเครื่องหมายดนตรี/โครงสร้าง (หนึ่งท่อนต่อหนึ่งบรรทัด เหมาะกับการตรวจรูปทรงข้อมูลก่อน):

import re

SKIP = re.compile(r"^\[.*\]$|^Instrumental:")

def to_lrc(segments):
    lines = []
    for seg in segments:
        if not seg.get("success", True):
            continue
        text = (seg.get("word") or "").strip()
        if not text or SKIP.match(text):
            continue
        cs = int(max(0.0, float(seg["start_s"])) * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

คำอธิบายความเข้ากันได้

เอกสารรุ่นก่อนหน้าใช้ตัวอย่างออบเจ็กต์ห่อ { success, song_id, lyrics: [...] } เอกสารรุ่นใหม่ปัจจุบันยึดการคืนอาร์เรย์ไทม์ไลน์โดยตรงเป็นหลัก