API di calibrazione dei timestamp del testo

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

Questo non è riconoscimento vocale. Il testo usa sempre il testo originale che fornisci tu; noi mettiamo solo ogni carattere nell'istante giusto — quindi non capita mai che «caratteri sentiti male disallineino il testo».

Descrizione dell'endpoint

Allinea un testo esistente a un audio e restituisce timestamp per riga e per carattere, per l'evidenziazione carattere per carattere tipo karaoke, il testo che scorre e la generazione di sottotitoli.

Endpoint: POST /api/music/lyrics-align

Autenticazione: vedi Autenticazione; l'header è Authorization: Bearer YOUR_API_KEY

Fatturazione: a chiamata (attualmente 0,1 ¥ per chiamata per impostazione predefinita); su un brano della piattaforma con separazione della voce spuntata, viene addebitato una volta in più il prezzo «separazione voce/base» della piattaforma. L'importo effettivo segue la configurazione prezzi del back-office.

Tempo medio: 5–15 secondi (dipende dalla durata dell'audio e dalla necessità di separare la voce sul momento)

Perché serve la calibrazione: i timestamp del lato generazione non sono sempre precisi

L'API di testi con timestamp restituisce direttamente i timestamp parola per parola del lato generazione e presentano imprecisioni:

• ripetizioni, armonie dense, rap e note lunghe tendono a slittare nel complesso o a spostare singoli caratteri;
• alcuni brani perdono un tratto all'inizio (per esempio un'intro pura, con il primo frammento che parte solo dopo i quindici secondi);
• alcune righe sono difficili da ancorare a un istante chiaro.

La calibrazione rifà l'allineamento temporale sul testo che fornisci tu: si corregge solo il tempo, mai il testo, il che serve ai casi in cui conta «se combacia» (evidenziazione per carattere tipo KTV, sottotitoli per carattere, valutazione del canto).

Approccio consigliato (tre passi, risultato migliore)

1. Estrai prima la voce (separazione voce/base) e allinea solo la traccia vocale — base e armonie smettono di disturbare. Base misurata: in un confronto riga per riga «mix completo vs traccia vocale» dello stesso brano, 5 righe su 28 differivano di oltre 0,25 s (la maggiore, 2,64 s); due motori indipendenti differivano in media di 0,239 s sulla traccia vocale e di 0,508 s sul mix completo — quasi la metà della concordanza. Per l'evidenziazione per carattere (KTV/sottotitoli) conviene quindi attivarla. (Il guadagno esatto è in corso di nuova misura con il motore nuovo.)
2. Fornisci il testo completo: tutto il brano, riga per riga, in corrispondenza uno a uno con l'audio. Una frase o una sezione mancante sposta tutte le righe successive; non inserire timestamp come [00:23.82] nel testo (vengono ignorati automaticamente).
3. Su un brano della piattaforma basta spuntare vocal_separate: true e facciamo «separazione + allineamento» in un solo passo.

Tre modi di usarla

Come sono legati i parametri (è qui che si sbaglia di più: leggi con attenzione)

• Inviare song_id → percorso brano della piattaforma: non inviare anche lyrics / audio_url / audio_object_key;
• Inviare audio_url o audio_object_key → percorso brano esterno: solo uno dei due e non inviare song_id;
• vocal_separate funziona solo sui brani della piattaforma; su un brano esterno viene rifiutato (l'audio non è dalla nostra parte, non si può separare).

Novità: invio diretto di un file locale (l'audio non passa dai nostri server)

Usalo quando l'audio è sulla tua macchina e preferisci non caricarlo prima nel tuo spazio pubblico. Due passi:

1. POST /api/music/lyrics-align/upload-ticket con file_name / file_size / content_type e ricevi una put_url (URL firmato, senza credenziali di lunga durata) e un object_key;
2. Fai un PUT del file su put_url, portando il content_type della risposta così com'è (partecipa alla firma; un carattere cambiato dà 403);
3. All'invio dell'allineamento, manda audio_object_key invece di audio_url.

La credenziale è monouso: finito l'allineamento (successo o errore) il server cancella l'oggetto e riusare la stessa chiave dà errore.

Novità: il testo è diventato opzionale

Prima un brano esterno richiedeva il testo. Ora puoi ometterlo: il server esegue un riconoscimento e usa il testo riconosciuto come testo del brano.

Il compromesso va detto chiaramente: il testo dipende dal risultato del riconoscimento, quindi qualche carattere può essere sbagliato. Queste risposte sono marcate con lyrics_source: "asr", confidence: "low" e, in warnings[], {"code":"no_reference_lyrics"}.

Per l'evidenziazione per carattere / KTV, fornisci sempre il testo originale.

Parametri della richiesta

Headers

Parametri del body

Limiti

Esempi di richiesta

Brano esterno (testo + indirizzo 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": "Cammino per strade fredde\nLa brezza notturna sfiora i miei occhi\nIl tempo scorre come l'\''acqua",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

Brano della piattaforma (senza separazione)

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

Brano della piattaforma + separazione della voce (consigliato per il 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}'

Risposta

Risposta di successo

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "Cammino per strade fredde",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "C", "start": 21.66, "end": 21.74, "word": true},
        {"char": "a", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

Riferimento dei campi

Come usare coverage (tre fasce)

Stato e tempi

Il limite di una singola esecuzione sul server è 8 minuti; imposta il timeout del client a 120 secondi o più.

Risposte di errore

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

Principio: senza risultato finale, rimborso totale. Si addebita solo quando i timestamp per carattere vengono davvero restituiti, e il rimborso è automatico, senza richiesta.

Fatturazione

La combinazione:

da pagare = prezzo base + (testo non fornito ? supplemento di trascrizione : 0) + (separazione spuntata ? prezzo separazione : 0)

La separazione della voce si addebita una sola volta: se hai già separato e la traccia vocale è disponibile, la addebita questo endpoint; se la separazione serve sul momento, la addebita lo step di separazione.

Esempio completo (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("qualità dell'allineamento coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # karaoke per carattere: ogni carattere in line["chars"] ha il suo start / end

Domande frequenti

D: L'output è per carattere o per riga? R: Entrambi. lines[].start è per riga, lines[].chars[].start / end per carattere; il player prende quello che serve.

D: Perché il testo restituito è identico a quello che ho inviato? R: È il progetto. Non riconosciamo né riscriviamo, allineiamo solo i tempi, quindi il testo non può mai essere «corretto in refuso».

D: Il coverage è alto ma suona ancora un po' spostato. R: L'errore per carattere è di solito nell'ordine di decine di millisecondi; se tutto il brano è spostato di un valore fisso, molto probabilmente c'è un tratto di silenzio all'inizio dell'audio: taglialo e riprova.

D: Perché poco fa la separazione andava e ora dice «traccia vocale non disponibile»? R: I risultati della separazione sono indirizzi temporanei di breve durata (misurato: scadono dopo circa mezz'ora). In quel caso l'endpoint prova a separare di nuovo; se fallisce ancora, c'è rimborso totale. Quindi «separo adesso e calibro dopo» non è affidabile: fai le due cose nello stesso flusso.

D: Devo separare io un brano della piattaforma? R: No. Con vocal_separate: true controlliamo se il brano ha già una traccia vocale; se non ce n'è una utilizzabile, diamo errore e rimborso invece di rifilare il mix completo.

D: Si possono fare lotti? R: Un brano per richiesta. Per i lotti fai un ciclo; ogni chiamata viene addebitata normalmente, quindi conviene mettere i risultati in cache.

D: Il risultato viene salvato? R: Questo endpoint non persiste nulla; salva tu il valore restituito (i timestamp per riga e per carattere sono nella risposta).