Zaman damgalı şarkı sözü API'si

2026-09-18 tarihinde güncellendi · Suno-API ekibi

Uç nokta açıklaması

Zaman damgalı şarkı sözü, bir şarkının kelime düzeyindeki zaman damgalarını getirir; sözlerin senkron gösterimi için kullanılır.

Uç nokta: POST /api/lyrics/timeline

Faturalama: Ücretsiz (yalnızca okuma sorgusu; hiçbir ücret alınmaz ve üretim görevi oluşturulmaz).

Dönüş biçimi: zaman çizelgesi dizisi doğrudan döndürülür — data / success sarmalayıcısı yoktur; ayrıştırıldığında yalnızca bir dizidir.

İstek parametreleri

Headers

Gövde parametreleri

İstek örneği

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

Yanıt

Aşağıda, üretim ortamında 189,6 saniyelik bir suno-v6 şarkısı için gerçek yanıt var (o çağrıda 69 segment vardı; burada yalnızca baş ve son birkaç segment tutuldu):

[
  {
    "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
  }
]

Alan referansı

Dikkat edilmesi gerekenler

1. Sarmalayıcı aramayın. Yanıt dizinin kendisidir, {"data": ...} değildir ve success alanı da yoktur.
2. Başta segment olmayabilir. Yalnızca girişi olan şarkılarda ölçüm ilk segmentin ancak 15. saniyede göründüğünü gösterdi ve start_s değerinin 0dan başlaması garanti değildir; karaoke için baştaki boşluğu kendiniz işleyin.
3. Enstrümantal ve yapı işaretleri de döner, [Intro], [Verse 1], Instrumental: soft arpeggiating piano, …, [End] gibi biçimlerde ve yine kelime kelime zamanlıdır. Söz altyazısı yapmadan önce bu segmentleri baştaki [ ya da Instrumental ile süzün; aksi halde düzenleme açıklamaları söz gibi görünür.
4. Kelime bazlıdır, satır bazlı değildir. Aynı söz satırı sıklıkla birkaç segmente bölünür ve \n ile satırlara birleştirilmelidir; bir satırın zamanı ilk segmentinin start_s değeridir.
5. Segment sayısı şarkıya bağlıdır; sabit bir sayı varsaymayın (ölçüm: 189,6 saniyelik şarkıda 69 segment ve yaklaşık 6,5 KB yanıt gövdesi).

.lrc dosyası oluşturma

Bu uç nokta yalnızca zaman çizelgesi verisini döndürür; doğrudan dosya döndürmez. .lrc gerekiyorsa dönen start_s değerinden [mm:ss.cc] biçiminde satırlar kurun (word alanı kendi satır sonlarını taşır — satırlara bölün ve boş satırları atlayın). Örnek için Şarkı medyası indirme ve önizleme API'si sayfasındaki "Zaman damgalı sözler (.lrc) nasıl alınır" bölümüne bakın.

Aşağıda enstrümantal/yapı işareti süzgeci içeren tam sürüm var (satır başına bir segment, önce veri şeklini doğrulamak için uygundur):

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)

Uyumluluk notları

Eski belgeler { success, song_id, lyrics: [...] } sarmalayıcı nesnesi örneğini kullanıyordu. Güncel belgeler doğrudan dönen zaman çizelgesi dizisini esas alır.