가사 타임스탬프 보정 API

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

이것은 음성 인식이 아닙니다. 글자는 항상 고객님이 주신 가사 원문을 그대로 사용하며, 저희는 각 글자를 올바른 시점에 놓을 뿐입니다 — 따라서 "인식 오타 때문에 가사가 어긋나는" 일은 없습니다.

인터페이스 설명

이미 있는 가사와 오디오를 정렬해 줄 단위 + 글자 단위 타임스탬프를 출력합니다. 노래방 글자 하이라이트, 스크롤 가사, 자막 생성에 씁니다.

엔드포인트: POST /api/music/lyrics-align

인증: 인증 안내를 참고하세요. 요청 헤더는 Authorization: Bearer YOUR_API_KEY

과금: 호출당 과금(현재 기본 1회 0.1위안). 플랫폼 곡에서 보컬 분리를 선택하면 플랫폼의 "보컬/반주 분리" 가격으로 한 번 더 과금됩니다. 실제 청구 금액은 현재 백오피스 가격 설정을 따릅니다.

평균 소요 시간: 5~15초(오디오 길이와 현장에서 보컬 분리가 필요한지에 따라 다릅니다)

보정이 필요한 이유: 생성 측 타임스탬프는 항상 정확하지 않습니다

타임라인 가사 API는 생성 측의 단어별 타임스탬프를 그대로 돌려주며, 부정확한 부분이 있습니다:

• 반복 구간, 화음이 많은 곡, 랩, 긴 음에서는 전체가 밀리거나 일부 글자가 어긋나기 쉽습니다;
• 일부 곡은 앞부분이 빠져 있습니다(예: 순수 전주라 첫 조각이 십몇 초에서 시작);
• 어떤 가사 줄은 명확한 시간 앵커를 잡기 어렵습니다.

가사 타임스탬프 보정은 고객님이 제공한 가사를 바탕으로 시간 정렬을 다시 하는 것으로, 시간만 보정하고 글자는 바꾸지 않습니다. "맞아떨어지는가"가 중요한 용도(노래방 글자 하이라이트, 글자 자막, 따라 부르기 채점)에 적합합니다.

권장 절차(3단계, 효과가 가장 좋음)

1. 먼저 순수 보컬을 추출(보컬/반주 분리)하고 보컬 트랙만 정렬하세요 — 반주와 화음이 더 이상 방해하지 않습니다. 실측 근거: 같은 곡의 "풀 믹스 vs 보컬 트랙"을 줄별로 비교했을 때 28줄 중 5줄이 0.25초 이상 어긋났습니다(최대 2.64초). 서로 독립적인 두 엔진은 보컬 트랙에서 평균 차이 0.239초, 풀 믹스에서 0.508초 — 일치도가 거의 두 배 차이입니다. 따라서 글자 하이라이트(노래방/자막)에는 켜는 것을 권장합니다. (개선 폭은 새 엔진으로 재측정 중입니다.)
2. 완전한 가사를 제공하세요: 곡 전체, 줄 단위, 오디오와 일대일. 문장이나 구간이 빠지면 뒤의 줄이 전체적으로 밀립니다. 가사에 [00:23.82] 같은 타임스탬프를 넣지 마세요(넣어도 자동으로 무시됩니다).
3. 플랫폼 곡이라면 vocal_separate: true만 붙이면 저희가 "분리 + 정렬"을 한 번에 처리합니다.

세 가지 사용법

파라미터 관계(가장 헷갈리는 부분이니 꼭 확인하세요)

• song_id를 보내면 → 플랫폼 곡 경로: lyrics / audio_url / audio_object_key를 함께 보내지 마세요;
• audio_url 또는 audio_object_key를 보내면 → 외부 곡 경로: 둘 중 하나만 보내고 song_id는 보내지 마세요;
• vocal_separate는 플랫폼 곡에만 유효하며, 외부 곡에서 보내면 거부됩니다(오디오가 저희 쪽에 없어 분리할 수 없습니다).

추가: 로컬 파일 직접 업로드(오디오가 저희 서버를 거치지 않습니다)

오디오가 고객님 컴퓨터에 있고 자체 공개 스토리지에 먼저 올리기 싫을 때 사용합니다. 두 단계입니다:

1. POST /api/music/lyrics-align/upload-ticket을 file_name / file_size / content_type과 함께 호출해 put_url(장기 자격 증명이 없는 서명 URL)과 object_key를 받습니다;
2. 파일을 put_url로 PUT합니다. 응답의 content_type을 그대로 붙여야 합니다(서명에 포함되므로 한 글자만 달라도 403입니다);
3. 정렬을 제출할 때 audio_url 대신 audio_object_key를 보냅니다.

자격 증명은 일회용입니다: 정렬이 끝나면(성공·실패 무관) 서버가 이 객체를 삭제하고, 같은 key를 다시 쓰면 오류가 납니다.

추가: 가사를 생략할 수 있게 되었습니다

예전에는 외부 곡에 가사가 필수였습니다. 이제 보내지 않아도 됩니다 — 서버가 먼저 한 번 인식하고, 인식된 글자를 가사로 사용합니다.

대가는 분명히 밝혀야 합니다: 글자는 인식 결과가 기준이므로 일부 글자가 부정확할 수 있습니다. 그런 응답에는 lyrics_source: "asr", confidence: "low"가 명시되고 warnings[]에 {"code":"no_reference_lyrics"}가 들어갑니다.

글자 하이라이트 / 노래방을 만들려면 반드시 가사 원문을 제공하세요.

요청 파라미터

Headers

Body 파라미터

제한

요청 예시

외부 곡(가사 + 오디오 주소)

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": "차가운 거리를 걸어간다\n밤바람이 눈시울을 스친다\n시간은 물처럼 흘러간다",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

플랫폼 곡(분리 없음)

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

플랫폼 곡 + 보컬 분리(노래방에 권장)

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

응답 결과

성공 응답

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "차가운 거리를 걸어간다",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "차", "start": 21.66, "end": 21.74, "word": true},
        {"char": "가", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

필드 설명

coverage 활용법(3단계 권장)

상태와 소요 시간

서버 측 1회 실행 상한은 8분입니다. 클라이언트 타임아웃은 120초 이상을 권장합니다.

오류 응답

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

원칙: 최종 결과를 얻지 못하면 전액 환불. 글자 타임스탬프가 실제로 반환된 경우에만 과금되며, 환불은 자동으로 처리되어 신청이 필요 없습니다.

과금

조합 관계:

실제 결제 = 기준가 + (가사 미제공 ? 전사 부가 요금 : 0) + (분리 선택 ? 분리 가격 : 0)

보컬 분리 요금은 한 번만: 이미 분리해서 보컬 트랙을 바로 쓸 수 있으면 이 엔드포인트가, 현장 분리가 필요하면 분리 단계가 부과합니다.

전체 예시(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("정렬 품질 coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # 글자 단위 노래방: line["chars"]의 각 글자에 start / end가 있습니다

자주 묻는 질문

Q: 반환되는 것이 글자 단위인가요, 줄 단위인가요? A: 둘 다입니다. lines[].start는 줄 단위, lines[].chars[].start / end는 글자 단위이며 플레이어가 필요한 쪽을 씁니다.

Q: 왜 반환된 글자가 제가 보낸 것과 똑같나요? A: 설계가 그렇습니다. 저희는 인식으로 고쳐 쓰지 않고 시간 정렬만 하므로 가사가 "오타로 바뀌는" 일은 없습니다.

Q: coverage는 높은데 아직 조금 밀려 들립니다. A: 글자 정렬 오차는 보통 수십 밀리초 수준입니다. 곡 전체가 일정하게 밀린다면 오디오 앞부분에 무음이 있을 가능성이 크니 잘라낸 뒤 다시 시도하세요.

Q: 방금은 보컬 분리로 됐는데 잠시 뒤 "보컬 트랙을 쓸 수 없음"이라고 합니다. A: 분리 결과는 짧은 수명의 임시 주소입니다(실측 약 30분 후 만료). 그 경우 엔드포인트가 자동으로 다시 분리를 시도하고, 그래도 실패하면 전액 환불합니다. 따라서 "먼저 분리하고 나중에 보정"은 믿을 수 없으니 같은 흐름에서 연달아 하세요.

Q: 플랫폼 곡은 제가 먼저 분리해야 하나요? A: 아닙니다. vocal_separate: true를 붙이면 그 곡에 보컬 트랙이 있는지 확인합니다. 쓸 수 있는 보컬 트랙이 없으면 오류를 내고 환불합니다(원곡으로 얼버무리지 않습니다).

Q: 배치로 할 수 있나요? A: 요청 1회에 1곡입니다. 배치는 반복 호출하세요. 매 호출마다 정상 과금되므로 결과를 로컬에 캐시하는 것을 권장합니다.

Q: 결과가 저장되나요? A: 이 엔드포인트는 저장하지 않습니다. 반환값을 직접 보관하세요(줄 단위 + 글자 단위 타임스탬프가 모두 응답에 있습니다).