API de letras com marcas de tempo

Atualizado em 2026-09-18 · equipe Suno-API

Descrição do endpoint

As letras com marcas de tempo obtêm as marcas de tempo ao nível da palavra de uma música, para apresentação sincronizada da letra.

Endpoint: POST /api/lyrics/timeline

Cobrança: Grátis (consulta só de leitura; não se cobra nada e não se cria qualquer tarefa de geração).

Formato de retorno: o array da linha do tempo é devolvido diretamente — não há envelope data / success; depois de analisado é simplesmente um array.

Parâmetros da requisição

Headers

Parâmetros do corpo

Exemplo de requisição

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

Resposta

Abaixo está uma resposta real de produção de uma música de 189,6 segundos em suno-v6 (essa chamada teve 69 segmentos; aqui só se mantêm os primeiros e os últimos):

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

Referência de campos

Coisas a ter em atenção

1. Não procure um envelope. A resposta é o próprio array, não {"data": ...}, e também não tem campo success.
2. Pode não haver segmento no início. Numa música com introdução pura, a medição mostrou o primeiro segmento só ao segundo 15, e não há garantia de que start_s comece em 0; para karaoke, trate você mesmo o intervalo inicial.
3. Também são devolvidos marcadores instrumentais e de estrutura, em formas como [Intro], [Verse 1], Instrumental: soft arpeggiating piano, … e [End], igualmente com tempos palavra a palavra. Antes de montar legendas de letra, filtre estes segmentos pelo [ inicial ou por Instrumental; caso contrário verá descrições do arranjo como se fossem letra.
4. É por palavra, não por linha. A mesma linha de letra costuma ser dividida em vários segmentos e tem de ser unida em linhas por \n; a hora de uma linha é o start_s do seu primeiro segmento.
5. O número de segmentos depende da música; não assuma uma quantidade fixa (medido: uma música de 189,6 segundos tinha 69 segmentos e um corpo de resposta de cerca de 6,5 KB).

Gerar um ficheiro .lrc

Este endpoint devolve apenas dados da linha do tempo; não devolve um ficheiro diretamente. Quando precisar de .lrc, construa as linhas a partir do start_s devolvido no formato [mm:ss.cc] (o campo word inclui as suas próprias quebras de linha: divida por linha e salte as linhas vazias). Para um exemplo, veja «Como obter a letra com marcas de tempo (.lrc)» na API de download e pré-visualização de mídia de músicas.

Abaixo está uma versão completa com filtragem de marcadores instrumentais e de estrutura (um segmento por linha, útil para verificar primeiro a forma dos dados):

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)

Notas de compatibilidade

A documentação anterior usava um exemplo com o objeto envelope { success, song_id, lyrics: [...] }. A documentação atual toma como referência o array da linha do tempo devolvido diretamente.