API de versuri cu marcaje de timp

Actualizat pe 2026-09-18 · echipa Suno-API

Descrierea endpoint-ului

Versurile cu marcaje de timp preiau marcaje de timp la nivel de cuvânt pentru o piesă, pentru afișarea sincronizată a versurilor.

Endpoint: POST /api/lyrics/timeline

Facturare: Gratuit (interogare doar în citire; nu se debitează nimic și nu se creează nicio sarcină de generare).

Format de returnare: tabloul cronologiei este returnat direct — nu există un înveliș data / success; după parsare este pur și simplu un tablou.

Parametrii cererii

Headers

Parametri din body

Exemplu de cerere

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

Răspuns

Mai jos este un răspuns real de producție pentru o piesă de 189,6 secunde în suno-v6 (acel apel a avut 69 de segmente; aici se păstrează doar primele și ultimele):

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

Referința câmpurilor

La ce să fii atent

1. Nu căuta un înveliș. Răspunsul este tabloul în sine, nu {"data": ...}, și nu are nici câmpul success.
2. La început poate lipsi un segment. La o piesă cu intro pur, măsurătoarea a arătat primul segment abia la secunda 15, iar start_s nu începe garantat de la 0; pentru karaoke gestionează singur golul de la început.
3. Sunt returnate și marcajele instrumentale și de structură, în forme precum [Intro], [Verse 1], Instrumental: soft arpeggiating piano, … și [End], tot cu timpi cuvânt cu cuvânt. Înainte de a construi subtitrări, filtrează aceste segmente după [ inițial sau după Instrumental; altfel descrierile aranjamentului vor apărea ca versuri.
4. Este pe cuvinte, nu pe rânduri. Același rând de vers este adesea împărțit în mai multe segmente și trebuie unit în rânduri după \n; timpul unui rând este start_s al primului său segment.
5. Numărul de segmente depinde de piesă; nu presupune un număr fix (măsurat: o piesă de 189,6 secunde a avut 69 de segmente și un corp de răspuns de circa 6,5 KB).

Generarea unui fișier .lrc

Acest endpoint returnează doar datele cronologiei; nu returnează un fișier direct. Dacă ai nevoie de .lrc, construiește rândurile din start_s returnat în formatul [mm:ss.cc] (câmpul word conține propriile treceri la linie nouă — împarte pe rânduri și sari peste rândurile goale). Pentru un exemplu vezi „Cum se obține textul cu marcaje de timp (.lrc)” în API de descărcare și ascultare a conținutului media al pieselor.

Mai jos este o variantă completă cu filtrarea marcajelor instrumentale și de structură (un segment pe rând, utilă pentru a verifica mai întâi forma datelor):

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)

Note de compatibilitate

Documentația anterioară folosea un exemplu cu obiectul-înveliș { success, song_id, lyrics: [...] }. Documentația actuală consideră autoritar tabloul cronologiei returnat direct.