API kalibrasi timestamp lirik

Diperbarui 2026-09-18 · tim Suno-API

Ini bukan pengenalan suara. Teks selalu memakai lirik asli yang Anda berikan; kami hanya menempatkan setiap karakter pada waktu yang tepat — jadi "karakter yang salah dengar membuat lirik meleset" tidak akan terjadi.

Deskripsi endpoint

Menyelaraskan lirik yang sudah ada dengan audio dan mengembalikan timestamp per baris dan per karakter, untuk penyorotan karakter demi karakter ala karaoke, lirik bergulir, dan pembuatan subtitle.

Endpoint: POST /api/music/lyrics-align

Autentikasi: lihat Autentikasi; headernya Authorization: Bearer YOUR_API_KEY

Biaya: ditagih per panggilan (saat ini default 0,1 ¥ per panggilan); pada lagu platform dengan pisahkan vokal dicentang, sekali lagi dikenakan harga "pisahkan vokal/instrumen" platform. Jumlah yang benar-benar ditagih mengikuti konfigurasi harga di back-office.

Waktu rata-rata: 5–15 detik (tergantung panjang audio dan apakah vokal harus dipisahkan saat itu)

Mengapa perlu kalibrasi: timestamp sisi pembuatan tidak selalu akurat

API lirik bertimestamp mengembalikan timestamp per kata langsung dari sisi pembuatan, dan itu tidak akurat:

• pengulangan, harmoni padat, rap, dan nada panjang sering bergeser keseluruhan atau menggeser karakter tertentu;
• sebagian lagu kehilangan satu bagian di awal (misalnya intro murni, fragmen pertama baru mulai di detik belasan);
• sebagian baris sulit dipautkan ke jangkar waktu yang jelas.

Kalibrasi menyusun ulang penyelarasan waktu berdasarkan lirik yang Anda berikan sendiri: hanya waktu yang dikoreksi, teks tidak pernah diubah — cocok untuk kasus yang menuntut "pas atau tidak" (penyorotan per karakter ala KTV, subtitle per karakter, penilaian bernyanyi bersama).

Cara yang disarankan (tiga langkah, hasil terbaik)

1. Ekstrak vokal murni dulu (pisahkan vokal/instrumen) dan selaraskan hanya trek vokal — instrumen dan harmoni tidak lagi mengganggu. Dasar pengukuran: dalam perbandingan baris per baris "mix penuh vs trek vokal" lagu yang sama, 5 dari 28 baris berbeda lebih dari 0,25 detik (terbesar 2,64 detik); dua mesin yang independen berbeda rata-rata 0,239 detik pada trek vokal dan 0,508 detik pada mix penuh — konsistensinya hampir setengahnya. Jadi untuk penyorotan per karakter (KTV/subtitle) sebaiknya diaktifkan. (Besaran peningkatannya sedang diukur ulang dengan mesin baru.)
2. Berikan lirik lengkap: seluruh lagu, per baris, cocok satu-satu dengan audio. Kalimat atau bagian yang hilang akan menggeser seluruh baris berikutnya; jangan sertakan timestamp seperti [00:23.82] di lirik (otomatis diabaikan).
3. Untuk lagu platform cukup centang vocal_separate: true, dan kami melakukan "pisahkan + selaraskan" dalam satu langkah.

Tiga cara pemakaian

Hubungan parameternya (paling sering salah — baca dengan saksama)

• Mengirim song_id → jalur lagu platform: jangan kirim lyrics / audio_url / audio_object_key juga;
• Mengirim audio_url atau audio_object_key → jalur lagu eksternal: hanya salah satu, dan jangan kirim song_id;
• vocal_separate hanya berlaku untuk lagu platform; pada lagu eksternal akan ditolak (audionya tidak ada di sisi kami, tidak bisa dipisahkan).

Baru: unggah langsung berkas lokal (audio tidak melewati server kami)

Pakai ini bila audio ada di komputer Anda dan Anda tidak mau mengunggahnya dulu ke penyimpanan publik sendiri. Dua langkah:

1. POST /api/music/lyrics-align/upload-ticket dengan file_name / file_size / content_type dan Anda menerima put_url (URL bertanda tangan, tanpa kredensial jangka panjang) serta object_key;
2. Lakukan PUT berkas ke put_url, bawa content_type dari respons apa adanya (ikut serta dalam tanda tangan; satu karakter berubah berarti 403);
3. Saat mengirim penyelarasan, kirim audio_object_key alih-alih audio_url.

Kredensialnya sekali pakai: setelah penyelarasan selesai (berhasil atau gagal) server menghapus objek ini, dan memakai key yang sama lagi akan menghasilkan galat.

Baru: lirik kini boleh tidak dikirim

Dulu lagu eksternal wajib beri lirik. Sekarang boleh dilewatkan: server menjalankan pengenalan sekali dan memakai teks hasil pengenalan sebagai lirik.

Konsekuensinya harus dikatakan jelas: teksnya mengikuti hasil pengenalan, sehingga beberapa karakter bisa salah. Respons seperti itu ditandai dengan lyrics_source: "asr", confidence: "low" dan di warnings[] ada {"code":"no_reference_lyrics"}.

Untuk penyorotan per karakter / KTV, selalu sediakan lirik aslinya.

Parameter permintaan

Headers

Parameter body

Batasan

Contoh permintaan

Lagu eksternal (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\nWaktu 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 (disarankan 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 berhasil

{
  "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 kolom

Cara memakai coverage (tiga tingkat)

Status dan durasi

Batas satu kali eksekusi di server adalah 8 menit; setel timeout klien 120 detik atau lebih.

Respons galat

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

Prinsip: tanpa hasil akhir berarti pengembalian penuh. Biaya dikenakan hanya bila timestamp per karakter benar-benar dikembalikan, dan pengembaliannya otomatis, tanpa permohonan.

Penagihan

Gabungannya:

bayar = harga dasar + (lirik tidak diberikan ? biaya transkripsi : 0) + (pemisahan dicentang ? harga pemisahan : 0)

Biaya pemisahan vokal hanya dikenakan sekali: jika Anda sudah memisahkan dan trek vokalnya langsung tersedia, endpoint ini yang menagih; jika harus dipisah saat itu, langkah pemisahan yang menagih.

Contoh lengkap (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("kualitas penyelarasan coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # karaoke per karakter: setiap karakter di line["chars"] punya start / end sendiri

Pertanyaan umum

T: Keluarannya per karakter atau per baris? J: Keduanya. lines[].start per baris, lines[].chars[].start / end per karakter; pemutar memakai yang diperlukan.

T: Kenapa teks yang dikembalikan sama persis dengan yang saya kirim? J: Memang begitu rancangannya. Kami tidak mengenali lalu menulis ulang, hanya menyelaraskan waktu, jadi lirik tidak akan pernah "dikoreksi jadi salah ketik".

T: coverage tinggi tapi masih terdengar agak meleset. J: Galat per karakter biasanya puluhan milidetik; kalau seluruh lagu meleset dengan nilai tetap, kemungkinan besar ada bagian sunyi di awal audio — potong dulu lalu coba lagi.

T: Kenapa tadi pemisahan bisa dipakai, sebentar kemudian bilang "trek vokal tidak tersedia"? J: Hasil pemisahan adalah alamat sementara berumur pendek (terukur: kedaluwarsa sekitar setengah jam). Dalam kasus itu endpoint mencoba memisahkan ulang otomatis; jika tetap gagal, ada pengembalian penuh. Jadi cara "pisahkan dulu, kalibrasi nanti" tidak andal — lakukan keduanya dalam satu alur.

T: Apakah lagu platform harus saya pisahkan sendiri dulu? J: Tidak. Dengan vocal_separate: true kami periksa apakah lagu sudah punya trek vokal; bila tidak ada yang bisa dipakai, kami beri galat dan mengembalikan dana, bukan menyodorkan mix penuh.

T: Bisa batch? J: Satu lagu per permintaan. Untuk batch, buat loop; setiap panggilan ditagih normal, jadi sebaiknya cache hasilnya secara lokal.

T: Apakah hasilnya disimpan? J: Endpoint ini tidak menyimpan apa pun; simpan sendiri nilai yang dikembalikan (timestamp per baris dan per karakter ada di respons).