API di testi con timestamp

Aggiornato il 2026-09-18 · team Suno-API

Descrizione dell'endpoint

I testi con timestamp recuperano i timestamp a livello di parola di un brano, per mostrare il testo sincronizzato.

Endpoint: POST /api/lyrics/timeline

Fatturazione: Gratuito (richiesta di sola lettura; non viene addebitato nulla e non viene creata alcuna attività di generazione).

Formato di ritorno: l'array della timeline viene restituito direttamente — non esiste un involucro data / success; una volta analizzato è semplicemente un array.

Parametri della richiesta

Headers

Parametri del corpo

Esempio di richiesta

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

Risposta

Qui sotto c'è una risposta reale di produzione per un brano di 189,6 secondi in suno-v6 (quella chiamata aveva 69 segmenti; qui sono conservati solo i primi e gli ultimi):

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

Riferimento dei campi

Cose a cui fare attenzione

1. Non cercare un involucro. La risposta è l'array stesso, non {"data": ...}, e non ha nemmeno un campo success.
2. All'inizio può non esserci alcun segmento. In un brano con sola introduzione, la misurazione ha mostrato il primo segmento solo al secondo 15, e start_s non è garantito partire da 0; per il karaoke gestisci tu lo spazio iniziale.
3. Vengono restituiti anche marcatori strumentali e di struttura, in forme come [Intro], [Verse 1], Instrumental: soft arpeggiating piano, … e [End], anch'essi con tempi parola per parola. Prima di costruire sottotitoli, filtra questi segmenti in base al [ iniziale o a Instrumental; altrimenti le descrizioni dell'arrangiamento verranno mostrate come testo.
4. È per parola, non per riga. La stessa riga di testo viene spesso divisa in più segmenti e va unita in righe tramite \n; l'ora di una riga è lo start_s del suo primo segmento.
5. Il numero di segmenti dipende dal brano; non dare per scontata una quantità fissa (misurato: un brano di 189,6 secondi aveva 69 segmenti e un corpo di risposta di circa 6,5 KB).

Generare un file .lrc

Questo endpoint restituisce solo i dati della timeline; non restituisce un file direttamente. Quando serve un .lrc, costruisci le righe dallo start_s restituito nel formato [mm:ss.cc] (il campo word contiene i propri a capo: dividi per riga e salta le righe vuote). Per un esempio vedi «Come ottenere il testo con timestamp (.lrc)» nell'API di download e anteprima dei media dei brani.

Qui sotto c'è una versione completa con il filtro dei marcatori strumentali e di struttura (un segmento per riga, utile per verificare prima la forma dei dati):

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 di compatibilità

La documentazione precedente usava un esempio con l'oggetto involucro { success, song_id, lyrics: [...] }. La documentazione attuale prende come riferimento l'array della timeline restituito direttamente.