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 КБ).

Створення файлу .lrc

Ця кінцева точка повертає лише дані таймлайна й не віддає файл напряму. Якщо потрібен .lrc, складіть рядки з повернутого start_s у форматі [mm:ss.cc] (поле word містить власні переведення рядків — розділіть за рядками й пропустіть порожні). Приклад див. у розділі «Як отримати текст із мітками часу (.lrc)» в API завантаження та прослуховування медіа пісень.

Нижче — повний варіант із фільтрацією інструментальних і структурних маркерів (один сегмент на рядок, зручно спершу перевірити форму даних):

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: [...] }. Поточна документація вважає правильним масив таймлайна, що повертається напряму.