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

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

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

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

จัดแนวเนื้อเพลงที่มีอยู่แล้วกับเสียง และคืนไทม์สแตมป์ระดับบรรทัด + ระดับตัวอักษร ใช้สำหรับไฮไลต์ทีละตัวอักษรแบบคาราโอเกะ เนื้อเพลงเลื่อน และการสร้างคำบรรยาย

เอนด์พอยต์: POST /api/music/lyrics-align

การยืนยันตัวตน: ดูการยืนยันตัวตน เฮดเดอร์คือ Authorization: Bearer YOUR_API_KEY

ค่าบริการ: คิดตามครั้ง (ปัจจุบันค่าเริ่มต้น 0.1 หยวนต่อครั้ง) หากเป็นเพลงของแพลตฟอร์มและติ๊กแยกเสียงร้อง จะคิดเพิ่มอีกหนึ่งครั้งตามราคา «แยกเสียงร้อง/ดนตรีประกอบ» ของแพลตฟอร์ม ยอดหักจริงเป็นไปตามการตั้งราคาในระบบหลังบ้าน

เวลาที่ใช้เฉลี่ย: 5–15 วินาที (ขึ้นกับความยาวเสียง และว่าต้องแยกเสียงร้องหน้างานหรือไม่)

ทำไมต้องปรับเทียบ: ไทม์สแตมป์ฝั่งผู้สร้างไม่ได้แม่นเสมอ

API เนื้อเพลงพร้อมไทม์สแตมป์ คืนไทม์สแตมป์รายคำจากฝั่งผู้สร้างโดยตรง และมีความคลาดเคลื่อน:

• ท่อนซ้ำ ฮาร์โมนีหนาแน่น แร็ป และโน้ตยาวมักเลื่อนทั้งท่อนหรือเลื่อนบางตัวอักษร
• บางเพลงขาดช่วงต้น (เช่น ช่วงดนตรีนำล้วน ๆ ชิ้นแรกเริ่มที่สิบกว่าวินาที)
• บางบรรทัดจับจุดอ้างอิงเวลาได้ยาก

การปรับเทียบจะจัดแนวเวลาใหม่บนพื้นฐานของเนื้อเพลงที่คุณให้เอง: แก้เฉพาะเวลา ไม่แก้ข้อความ จึงเหมาะกับงานที่ต้องการความ «ตรงเป๊ะ» (ไฮไลต์ทีละตัวแบบ KTV คำบรรยายรายตัว ให้คะแนนร้องตาม)

วิธีที่แนะนำ (สามขั้น ได้ผลดีที่สุด)

1. แยกเสียงร้องล้วนก่อน (แยกเสียงร้อง/ดนตรีประกอบ) แล้วจัดแนวเฉพาะแทร็กเสียงร้อง — ดนตรีประกอบและฮาร์โมนีจะไม่กวนอีก หลักฐานจากการวัด: ในการเทียบทีละบรรทัดระหว่าง «เพลงเต็ม vs แทร็กเสียงร้อง» ของเพลงเดียวกัน 28 บรรทัดมี 5 บรรทัดที่ต่างเกิน 0.25 วินาที (มากสุด 2.64 วินาที) สองเอนจินที่เป็นอิสระต่อกันต่างกันเฉลี่ย 0.239 วินาทีบนแทร็กเสียงร้อง และ 0.508 วินาทีบนเพลงเต็ม — ความสอดคล้องต่างกันเกือบเท่าตัว จึงแนะนำให้เปิดเมื่อทำไฮไลต์รายตัว (KTV/คำบรรยาย) (กำลังวัดอัตราการดีขึ้นจริงด้วยเอนจินใหม่)
2. ให้เนื้อเพลงครบถ้วน: ทั้งเพลง ทีละบรรทัด ตรงกับเสียงหนึ่งต่อหนึ่ง หากขาดประโยคหรือท่อน บรรทัดถัดไปจะเลื่อนทั้งหมด อย่าใส่ไทม์สแตมป์เช่น [00:23.82] ในเนื้อเพลง (ใส่แล้วระบบจะข้ามให้อัตโนมัติ)
3. เพลงของแพลตฟอร์มเพียงติ๊ก vocal_separate: true เราจะทำ «แยก + จัดแนว» ให้ในขั้นตอนเดียว

สามวิธีใช้งาน

ความสัมพันธ์ของพารามิเตอร์ (จุดที่ผิดพลาดบ่อยที่สุด โปรดอ่านให้ดี)

• ส่ง song_id → ใช้เส้นทางเพลงของแพลตฟอร์ม: อย่าส่ง lyrics / audio_url / audio_object_key อีก
• ส่ง audio_url หรือ audio_object_key → ใช้เส้นทางเพลงภายนอก: ส่งได้อย่างใดอย่างหนึ่งเท่านั้น และอย่าส่ง song_id
• vocal_separate ใช้ได้เฉพาะเพลงของแพลตฟอร์ม หากส่งมากับเพลงภายนอกจะถูกปฏิเสธ (เสียงไม่ได้อยู่ฝั่งเรา แยกไม่ได้)

เพิ่มใหม่: อัปโหลดไฟล์ในเครื่องตรง ๆ (เสียงไม่ผ่านเซิร์ฟเวอร์เรา)

ใช้เมื่อเสียงอยู่ในเครื่องคุณและไม่อยากอัปขึ้นที่จัดเก็บสาธารณะของคุณก่อน สองขั้นตอน:

1. เรียก POST /api/music/lyrics-align/upload-ticket พร้อม file_name / file_size / content_type จะได้ put_url (URL ที่ลงนามแล้ว ไม่มีข้อมูลรับรองระยะยาว) และ object_key
2. PUT ไฟล์ไปที่ put_url ต้องแนบ content_type จากคำตอบไปตามเดิม (มันร่วมในลายเซ็น เปลี่ยนหนึ่งตัวอักษรจะได้ 403)
3. ตอนส่งงานจัดแนว ให้ส่ง audio_object_key แทน audio_url

ข้อมูลรับรองใช้ครั้งเดียว: เมื่อจัดแนวเสร็จ (สำเร็จหรือล้มเหลว) เซิร์ฟเวอร์จะลบออบเจ็กต์นี้ ใช้ key เดิมซ้ำจะเกิดข้อผิดพลาด

เพิ่มใหม่: เนื้อเพลงไม่ส่งก็ได้แล้ว

เดิมเพลงภายนอกต้องมีเนื้อเพลง ตอนนี้ไม่ส่งก็ใช้ได้ — เซิร์ฟเวอร์จะรู้จำก่อนหนึ่งครั้ง แล้วใช้ข้อความที่รู้จำได้เป็นเนื้อเพลง

ต้องบอกให้ชัดถึงราคาที่ต้องจ่าย: ข้อความจะยึดผลการรู้จำเป็นหลัก บางตัวอักษรอาจไม่ถูกต้อง คำตอบลักษณะนี้จะระบุชัดว่า lyrics_source: "asr", confidence: "low" และใน warnings[] มี {"code":"no_reference_lyrics"}

หากจะทำไฮไลต์รายตัว / KTV กรุณาให้เนื้อเพลงต้นฉบับเสมอ

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

Headers

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

ข้อจำกัด

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

เพลงภายนอก (เนื้อเพลง + ที่อยู่เสียง)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lyrics": "เดินบนถนนหนาวเย็น\nลมกลางคืนแตะต้องดวงตา\nเวลาผ่านไปดั่งสายน้ำ",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

เพลงของแพลตฟอร์ม (ไม่แยก)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "17e52af7-b5df-4877-a98a-dce94e0e6aa2"}'

เพลงของแพลตฟอร์ม + แยกเสียงร้อง (แนะนำสำหรับคาราโอเกะ)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "17e52af7-b5df-4877-a98a-dce94e0e6aa2", "vocal_separate": true}'

คำตอบ

คำตอบที่สำเร็จ

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "เดินบนถนนหนาวเย็น",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "เ", "start": 21.66, "end": 21.74, "word": true},
        {"char": "ด", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

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

ใช้ coverage อย่างไร (สามระดับ)

สถานะและเวลาที่ใช้

ขีดจำกัดการรันครั้งเดียวฝั่งเซิร์ฟเวอร์คือ 8 นาที; แนะนำตั้ง timeout ฝั่งไคลเอนต์ไว้ที่ 120 วินาทีขึ้นไป

คำตอบข้อผิดพลาด

{
  "success": false,
  "message": "音频超过 6 分钟上限（实际 7.2 分钟）"
}

หลักการ: ไม่ได้ผลลัพธ์สุดท้ายก็คืนเงินเต็มจำนวน จะคิดค่าบริการเมื่อคืนไทม์สแตมป์รายตัวอักษรจริงเท่านั้น และการคืนเงินทำอัตโนมัติ ไม่ต้องยื่นคำขอ

ค่าบริการ

ความสัมพันธ์แบบรวม:

จ่ายจริง = ราคาฐาน + (ไม่ให้เนื้อเพลง ? ค่าเพิ่มการถอดข้อความ : 0) + (ติ๊กแยก ? ค่าแยก : 0)

ค่าแยกเสียงร้องเก็บเพียงครั้งเดียว: หากคุณแยกไว้แล้วและได้แทร็กเสียงร้องมาใช้ได้ทันที เอนด์พอยต์นี้จะเป็นผู้เก็บ; หากต้องแยกหน้างาน ขั้นตอนการแยกจะเป็นผู้เก็บ

ตัวอย่างเต็ม (Python)

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://www.suno-api.io"

def align_lyrics(song_id=None, lyrics=None, audio_url=None, vocal_separate=False):
    payload = {}
    if song_id:
        payload["song_id"] = song_id
        payload["vocal_separate"] = vocal_separate
    else:
        payload["lyrics"] = lyrics
        payload["audio_url"] = audio_url

    r = requests.post(
        f"{BASE}/api/music/lyrics-align",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=600,
    )
    data = r.json()
    if not data.get("success"):
        raise RuntimeError(data.get("message"))
    return data


res = align_lyrics(song_id="17e52af7-b5df-4877-a98a-dce94e0e6aa2", vocal_separate=True)
print("คุณภาพการจัดแนว coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # คาราโอเกะรายตัว: แต่ละตัวใน line["chars"] มี start / end ของตัวเอง

คำถามที่พบบ่อย

ถาม: ผลลัพธ์เป็นรายตัวหรือรายบรรทัด? ตอบ: ทั้งสอง lines[].start เป็นรายบรรทัด, lines[].chars[].start / end เป็นรายตัว โปรแกรมเล่นจะเลือกใช้ตามต้องการ

ถาม: ทำไมข้อความที่คืนมาตรงกับที่ผมส่งไปเป๊ะ? ตอบ: ออกแบบไว้เช่นนั้น เราไม่รู้จำแล้วเขียนใหม่ ทำเพียงจัดแนวเวลา เนื้อเพลงจึงไม่ถูก «แก้เป็นคำผิด»

ถาม: coverage สูง แต่ฟังดูยังเพี้ยนอยู่เล็กน้อย? ตอบ: ความคลาดเคลื่อนรายตัวมักอยู่ระดับสิบมิลลิวินาที; หากทั้งเพลงเพี้ยนเป็นค่าเดียวกันหมด มักเกิดจากมีช่วงเงียบที่ต้นเสียง ตัดออกแล้วลองใหม่ได้

ถาม: ทำไมแยกเสียงร้องเมื่อสักครู่ใช้ได้ ผ่านไปพักหนึ่งกลับบอก «แทร็กเสียงร้องใช้ไม่ได้»? ตอบ: ผลการแยกเป็นที่อยู่ชั่วคราวที่มีอายุสั้น (วัดได้ประมาณครึ่งชั่วโมงแล้วหมดอายุ) กรณีนี้เอนด์พอยต์จะลองแยกใหม่ให้อัตโนมัติ หากยังล้มเหลวจะคืนเงินเต็มจำนวน ดังนั้นวิธี «แยกก่อน แล้วค่อยปรับเทียบทีหลัง» ไม่น่าเชื่อถือ ควรทำต่อเนื่องในกระบวนการเดียวกัน

ถาม: เพลงของแพลตฟอร์มต้องแยกเองก่อนไหม? ตอบ: ไม่ต้อง เมื่อติ๊ก vocal_separate: true เราจะตรวจว่าเพลงนี้มีแทร็กเสียงร้องอยู่แล้วหรือไม่ หากไม่มีแทร็กที่ใช้ได้จะแจ้งข้อผิดพลาดและคืนเงิน ไม่ใช้เพลงต้นฉบับกลบเกลื่อน

ถาม: ทำเป็นชุดได้ไหม? ตอบ: หนึ่งคำขอหนึ่งเพลง หากเป็นชุดให้วนเรียก แต่ละครั้งคิดค่าบริการตามปกติ แนะนำให้แคชผลลัพธ์ไว้ในเครื่อง

ถาม: ผลลัพธ์ถูกบันทึกไหม? ตอบ: เอนด์พอยต์นี้ไม่บันทึก กรุณาเก็บค่าที่คืนมาเอง (ไทม์สแตมป์รายบรรทัดและรายตัวอยู่ในคำตอบแล้ว)