API калибровки таймкодов текста

Обновлено 2026-09-18 · команда Suno-API

Это не распознавание речи. Текст всегда берётся из вашего исходного текста песни; мы лишь ставим каждый символ в правильный момент — поэтому «сдвиг текста из-за неверно услышанных слов» невозможен.

Описание эндпоинта

Он выравнивает готовый текст песни по аудио и возвращает таймкоды по строкам и по символам — для подсветки по символам в стиле караоке, прокрутки текста и генерации субтитров.

Эндпоинт: POST /api/music/lyrics-align

Аутентификация: см. Аутентификация; заголовок — Authorization: Bearer YOUR_API_KEY

Оплата: за вызов (сейчас по умолчанию 0,1 ¥ за вызов); если у песни платформы отмечено разделение вокала, дополнительно один раз списывается по цене платформы «разделение вокала/аккомпанемента». Фактически списанная сумма следует текущей конфигурации цен в бэк-офисе.

Среднее время: 5–15 секунд (зависит от длины аудио и от того, нужно ли разделять вокал на месте)

Зачем нужна калибровка: таймкоды со стороны генерации не всегда точны

API текста с таймкодами возвращает таймкоды по словам прямо со стороны генерации, и они неточны:

• повторы, плотные гармонии, рэп и длинные ноты часто дают общий сдвиг или смещение отдельных символов;
• у части песен отсутствует кусок в начале (например, чистое интро, и первый фрагмент начинается только на пятнадцатой секунде);
• некоторые строки трудно привязать к явному временному якорю.

Калибровка заново делает выравнивание по времени на основе вашего собственного текста: правится только время, текст — никогда, что подходит для случаев, где важно «попадание» (подсветка по символам как в KTV, послоговые субтитры, оценка пения).

Рекомендуемый порядок (три шага, лучший результат)

1. Сначала извлеките вокал (разделение вокала/аккомпанемента) и выравнивайте только вокальную дорожку — аккомпанемент и гармонии больше не мешают. Основание по измерениям: при построчном сравнении «полный микс против вокальной дорожки» одной песни 5 из 28 строк различались более чем на 0,25 с (максимум — 2,64 с); два независимых движка расходились в среднем на 0,239 с на вокальной дорожке и на 0,508 с на полном миксе — почти вдвое хуже согласие. Поэтому для подсветки по символам (KTV/субтитры) её стоит включать. (Точный выигрыш сейчас перемеряется на новом движке.)
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 файла на put_url, передав content_type из ответа ровно как есть (он участвует в подписи; один изменённый символ даёт 403);
3. При отправке выравнивания передавайте audio_object_key вместо audio_url.

Учётные данные одноразовые: после завершения выравнивания (успешно или нет) сервер удаляет объект, и повторное использование того же key даёт ошибку.

Новое: текст теперь необязателен

Раньше для внешней песни текст был обязателен. Теперь его можно не передавать: сервер сначала выполняет распознавание и использует распознанный текст как текст песни.

Об этом нужно сказать прямо: текст тогда определяется результатом распознавания, отдельные символы могут быть неверны. Такие ответы помечаются lyrics_source: "asr", confidence: "low" и, в warnings[], {"code":"no_reference_lyrics"}.

Для подсветки по символам / KTV обязательно давайте исходный текст.

Параметры запроса

Headers

Параметры тела

Ограничения

Примеры запроса

Внешняя песня (текст + адрес аудио)

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 (три уровня)

Состояние и время выполнения

Лимит одного запуска на сервере — 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

Частые вопросы

В: Вывод по символам или по строкам? О: И то и другое. lines[].start — по строкам, lines[].chars[].start / end — по символам; плеер берёт, что нужно.

В: Почему возвращённый текст совпадает с отправленным? О: Так задумано. Мы не распознаём и не переписываем, а только выравниваем время, поэтому текст никогда не «исправится в опечатку».

В: coverage высокий, но всё равно звучит немного смещённо. О: Ошибка по символам обычно в пределах десятков миллисекунд; если вся песня смещена на постоянную величину, скорее всего, в начале аудио есть тишина — обрежьте её и попробуйте снова.

В: Почему только что разделение работало, а теперь «вокальная дорожка недоступна»? О: Результаты разделения — кратковременные адреса (по измерениям, истекают примерно через полчаса). Тогда эндпоинт пытается разделить заново; если и это не удалось — полный возврат. Поэтому «разделить сейчас, выровнять потом» ненадёжно: делайте оба шага в одном процессе.

В: Нужно ли самому разделять песню платформы? О: Нет. При vocal_separate: true мы проверяем, есть ли у песни вокальная дорожка; если пригодной нет, вернём ошибку и деньги, а не подсунем полный микс.

В: Можно пакетно? О: Одна песня за запрос. Для пакета делайте цикл; каждый вызов тарифицируется, поэтому результаты лучше кэшировать.

В: Результат сохраняется? О: Этот эндпоинт ничего не сохраняет; сохраняйте возвращённое значение сами (таймкоды по строкам и символам есть в ответе).