타임라인 가사 API

2026-09-18 업데이트 · Suno-API 팀

인터페이스 설명

타임라인 가사는 곡의 단어 단위 타임스탬프를 가져오는 기능으로, 가사 동기 표시에 쓸 수 있습니다.

엔드포인트: POST /api/lyrics/timeline

과금: 무료(읽기 전용 조회로, 요금이 청구되지 않고 생성 작업도 만들어지지 않습니다).

반환 형식: 타임라인 배열을 그대로 반환하며, data / success 외부 래퍼가 없습니다. 파싱하면 그대로 배열입니다.

요청 파라미터

Headers

바디 파라미터

요청 예시

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

응답 결과

아래는 프로덕션 환경의 189.6초 suno-v6 곡의 실제 반환입니다(해당 호출은 총 69개 구간이며, 여기서는 처음과 마지막 몇 구간만 남겼습니다):

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

필드 설명

사용 시 주의

1. 외부 래퍼를 찾지 마세요. 응답은 배열 자체이며 {"data": ...}가 아니고 success 필드도 없습니다.
2. 앞부분에 구간이 없을 수 있습니다. 전주만 있는 곡은 실측에서 15초에야 첫 구간이 나타났고, start_s가 0부터 시작한다는 보장도 없습니다. 노래방 용도라면 앞부분의 빈 구간을 직접 처리하세요.
3. 연주·구조 표시도 함께 반환됩니다. [Intro], [Verse 1], Instrumental: soft arpeggiating piano, …, [End] 같은 형태로 역시 단어 단위 시간이 붙습니다. 가사 자막을 만들기 전에 [로 시작하는 항목이나 Instrumental을 걸러내는 것을 권장합니다. 그렇지 않으면 편곡 설명이 가사로 표시됩니다.
4. 줄 단위가 아니라 단어 단위입니다. 같은 가사 한 줄이 여러 구간으로 나뉘는 경우가 많아 \n 기준으로 줄을 합쳐야 하며, 한 줄의 시간은 그 줄 첫 구간의 start_s입니다.
5. 구간 수는 곡마다 다릅니다. 고정된 구간 수를 가정하지 마세요(실측: 189.6초 곡은 69개 구간, 응답 본문 약 6.5 KB).

.lrc 파일 생성

이 엔드포인트는 타임라인 데이터만 반환하며 파일을 직접 반환하지 않습니다. .lrc가 필요하면 반환된 start_s로 [mm:ss.cc] 형식의 줄을 만들면 됩니다(word 필드에 줄바꿈이 들어 있으니 줄 단위로 나누고 빈 줄은 건너뜁니다). 예시는 곡 미디어 다운로드 및 미리듣기 API의 "타임라인 가사(.lrc) 가져오는 방법"을 참고하세요.

아래는 연주·구조 표시 필터를 포함한 전체 작성 예입니다(한 구간 한 줄, 먼저 데이터 형태를 확인하기에 적합):

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)

호환성 설명

이전 문서에서는 { success, song_id, lyrics: [...] } 래퍼 객체 예시를 사용했습니다. 현재 새 문서는 타임라인 배열을 그대로 반환하는 형태를 기준으로 합니다.