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: [...] }. Текущая документация считает правильным напрямую возвращаемый массив таймлайна.