API kalibrasi cap masa lirik

Dikemas kini 2026-09-18 · pasukan Suno-API

Ini bukan pengecaman pertuturan. Teks sentiasa menggunakan lirik asal yang anda berikan; kami hanya meletakkan setiap aksara pada masa yang betul — jadi "aksara yang salah didengar menyebabkan lirik tidak sepadan" tidak akan berlaku.

Penerangan endpoint

Ia menjajarkan lirik sedia ada dengan audio dan memulangkan cap masa peringkat baris dan aksara, untuk sorotan aksara demi aksara gaya karaoke, lirik bergulir dan penjanaan sari kata.

Endpoint: POST /api/music/lyrics-align

Pengesahan: lihat Pengesahan; pengepalanya Authorization: Bearer YOUR_API_KEY

Pengebilan: setiap panggilan (kini lalai 0.1 ¥ setiap panggilan); jika lagu platform dan pisahkan vokal ditanda, sekali lagi dikenakan harga "pisahkan vokal/iringan" platform. Jumlah yang benar-benar dicaj mengikut tetapan harga dalam back-office.

Masa purata: 5–15 saat (bergantung panjang audio dan sama ada vokal perlu dipisahkan di tempat)

Mengapa perlu kalibrasi: cap masa di sisi penjanaan tidak sentiasa tepat

API lirik bertimestamp memulangkan cap masa perkataan demi perkataan terus daripada sisi penjanaan, dan ia tidak tepat:

• ulangan, harmoni padat, rap dan not panjang sering bergeser keseluruhan atau menggeser aksara tertentu;
• sebahagian lagu kehilangan bahagian di awal (contohnya intro semata-mata, serpihan pertama baru bermula pada saat belasan);
• sesetengah baris sukar dipautkan pada sauh masa yang jelas.

Kalibrasi menyusun semula penjajaran masa berdasarkan lirik yang anda berikan sendiri: hanya masa dibetulkan, teks tidak pernah diubah — sesuai untuk kes yang mementingkan "betul-betul sepadan" (sorotan per aksara gaya KTV, sari kata per aksara, pemarkahan nyanyian bersama).

Cara yang disyorkan (tiga langkah, hasil terbaik)

1. Asingkan vokal tulen dahulu (pisahkan vokal/iringan) dan jajarkan hanya trek vokal — iringan dan harmoni tidak lagi mengganggu. Asas ukuran: dalam perbandingan baris demi baris "campuran penuh vs trek vokal" lagu yang sama, 5 daripada 28 baris berbeza lebih 0.25 saat (terbesar 2.64 saat); dua enjin bebas berbeza purata 0.239 saat pada trek vokal dan 0.508 saat pada campuran penuh — ketekalan hampir separuh. Jadi untuk sorotan per aksara (KTV/sari kata) sebaiknya dihidupkan. (Peningkatan sebenar sedang diukur semula dengan enjin baharu.)
2. Berikan lirik lengkap: seluruh lagu, baris demi baris, sepadan satu dengan satu dengan audio. Ayat atau bahagian yang hilang akan menggeser semua baris berikutnya; jangan masukkan cap masa seperti [00:23.82] dalam lirik (ia diabaikan automatik).
3. Untuk lagu platform, cukup tanda vocal_separate: true dan kami buat "pisah + jajar" dalam satu langkah.

Tiga cara penggunaan

Hubungan parameter (paling kerap tersalah — baca dengan teliti)

• Menghantar song_id → laluan lagu platform: jangan hantar lyrics / audio_url / audio_object_key sekali lagi;
• Menghantar audio_url atau audio_object_key → laluan lagu luar: hanya satu daripada dua, dan jangan hantar song_id;
• vocal_separate hanya berkesan untuk lagu platform; jika dihantar pada lagu luar ia ditolak (audio bukan di pihak kami, tidak boleh dipisahkan).

Baharu: muat naik terus fail tempatan (audio tidak melalui pelayan kami)

Gunakan apabila audio ada pada mesin anda dan anda tidak mahu memuat naiknya ke storan awam sendiri dahulu. Dua langkah:

1. POST /api/music/lyrics-align/upload-ticket dengan file_name / file_size / content_type dan anda menerima put_url (URL bertandatangan, tanpa kredensial jangka panjang) serta object_key;
2. Lakukan PUT fail ke put_url, bawa content_type daripada respons sebagaimana adanya (ia terlibat dalam tandatangan; satu aksara berubah bermakna 403);
3. Semasa menghantar penjajaran, hantar audio_object_key dan bukan audio_url.

Kredensial adalah sekali guna: setelah penjajaran selesai (berjaya atau gagal) pelayan akan memadam objek ini, dan menggunakan key yang sama semula akan menyebabkan ralat.

Baharu: lirik kini boleh tidak dihantar

Dahulu lagu luar wajib ada lirik. Kini boleh ditinggalkan: pelayan menjalankan pengecaman sekali dan menggunakan teks yang dikecam sebagai lirik.

Kosnya mesti dinyatakan jelas: teks mengikut hasil pengecaman, jadi beberapa aksara mungkin salah. Respons sebegitu ditandakan dengan lyrics_source: "asr", confidence: "low" dan dalam warnings[] ada {"code":"no_reference_lyrics"}.

Untuk sorotan per aksara / KTV, sentiasa berikan lirik asal.

Parameter permintaan

Headers

Parameter body

Had

Contoh permintaan

Lagu luar (lirik + alamat audio)

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": "Berjalan di jalan yang dingin\nAngin malam menyentuh mataku\nMasa mengalir seperti air",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

Lagu platform (tanpa pemisahan)

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"}'

Lagu platform + pisahkan vokal (disyorkan untuk karaoke)

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}'

Respons

Respons berjaya

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "Berjalan di jalan yang dingin",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "B", "start": 21.66, "end": 21.74, "word": true},
        {"char": "e", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

Penjelasan medan

Cara guna coverage (tiga tahap)

Status dan masa

Had satu larian di pelayan ialah 8 minit; tetapkan timeout klien 120 saat atau lebih.

Respons ralat

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

Prinsip: tiada hasil akhir bermakna bayaran balik penuh. Caj dikenakan hanya apabila cap masa per aksara benar-benar dipulangkan, dan bayaran balik dibuat automatik, tanpa permohonan.

Pengebilan

Gabungannya:

bayar = harga asas + (lirik tidak diberi ? caj transkripsi : 0) + (pemisahan ditanda ? harga pemisahan : 0)

Kos pemisahan vokal dikenakan sekali sahaja: jika anda sudah memisahkan dan trek vokal tersedia terus, endpoint ini yang mengenakannya; jika perlu dipisah di tempat, langkah pemisahan yang mengenakannya.

Contoh penuh (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("kualiti penjajaran coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # karaoke per aksara: setiap aksara dalam line["chars"] ada start / end sendiri

Soalan lazim

S: Output per aksara atau per baris? J: Kedua-duanya. lines[].start per baris, lines[].chars[].start / end per aksara; pemain ambil yang perlu.

S: Mengapa teks yang dipulangkan sama dengan yang saya hantar? J: Memang begitu rekaannya. Kami tidak mengecam lalu menulis semula, hanya menjajarkan masa, jadi lirik tidak akan "dibetulkan menjadi salah taip".

S: coverage tinggi tetapi masih kedengaran sedikit melencong. J: Ralat per aksara biasanya puluhan milisaat; kalau seluruh lagu melencong dengan nilai tetap, kemungkinan besar ada bahagian senyap di awal audio — potong dahulu lalu cuba lagi.

S: Mengapa tadi pemisahan boleh guna, sebentar kemudian berkata "trek vokal tidak tersedia"? J: Hasil pemisahan ialah alamat sementara berumur pendek (diukur: luput kira-kira setengah jam). Dalam kes itu endpoint akan cuba memisahkan semula secara automatik; jika tetap gagal, ada bayaran balik penuh. Jadi cara "pisah dahulu, kalibrasi kemudian" tidak boleh dipercayai — buat kedua-duanya dalam aliran yang sama.

S: Perlukah saya pisahkan lagu platform sendiri dahulu? J: Tidak. Dengan vocal_separate: true kami semak sama ada lagu sudah ada trek vokal; jika tiada yang boleh guna, kami beri ralat dan memulangkan dana, bukan menyuap campuran penuh.

S: Boleh berkelompok? J: Satu lagu setiap permintaan. Untuk kelompok, buat gelung; setiap panggilan dicaj seperti biasa, jadi sebaiknya cache hasil secara tempatan.

S: Hasilnya disimpan? J: Endpoint ini tidak menyimpan apa-apa; simpan sendiri nilai yang dipulangkan (cap masa per baris dan per aksara ada dalam respons).