API kalibracji znaczników czasu tekstu

Zaktualizowano 2026-09-18 · zespół Suno-API

To nie jest rozpoznawanie mowy. Tekst zawsze pochodzi z oryginalnego tekstu, który podajesz; my tylko umieszczamy każdy znak w odpowiednim momencie — więc „przesunięcie tekstu przez źle usłyszane znaki" nie występuje.

Opis punktu końcowego

Wyrównuje istniejący tekst do dźwięku i zwraca znaczniki czasu dla wiersza i dla znaku — do podświetlania znak po znaku w stylu karaoke, przewijania tekstu i generowania napisów.

Punkt końcowy: POST /api/music/lyrics-align

Uwierzytelnianie: zobacz Uwierzytelnianie; nagłówek to Authorization: Bearer YOUR_API_KEY

Rozliczenie: za wywołanie (obecnie domyślnie 0,1 juana za wywołanie); jeśli w utworze platformy zaznaczono separację wokalu, dodatkowo naliczana jest raz cena platformy „rozdzielanie wokalu/podkładu". Faktycznie pobierana kwota zależy od konfiguracji cen w panelu administracyjnym.

Średni czas: 5–15 sekund (zależnie od długości dźwięku i od tego, czy wokal trzeba rozdzielić na miejscu)

Dlaczego kalibracja jest potrzebna: znaczniki po stronie generowania nie zawsze są dokładne

API tekstu ze znacznikami czasu zwraca znaczniki słowo po słowie prosto ze strony generowania i są one niedokładne:

• powtórzenia, gęste harmonie, rap i długie dźwięki często przesuwają się całościowo albo przesuwają pojedyncze znaki;
• niektórym utworom brakuje fragmentu na początku (np. czyste intro, a pierwszy fragment zaczyna się dopiero w kilkunastej sekundzie);
• niektóre wiersze trudno przypiąć do wyraźnego punktu w czasie.

Kalibracja robi wyrównanie czasowe od nowa na podstawie podanego przez Ciebie tekstu: korygowany jest tylko czas, nigdy tekst — to pasuje do przypadków, w których liczy się „czy się zgadza" (podświetlanie znak po znaku jak w KTV, napisy po znaku, ocena śpiewania).

Zalecany sposób (trzy kroki, najlepszy efekt)

1. Najpierw wyodrębnij wokal (rozdzielanie wokalu/podkładu) i wyrównuj tylko ścieżkę wokalu — podkład i harmonie przestają przeszkadzać. Podstawa z pomiarów: w porównaniu wiersz po wierszu „pełny miks vs ścieżka wokalu" tego samego utworu 5 z 28 wierszy różniło się o ponad 0,25 s (największe o 2,64 s); dwa niezależne silniki różniły się średnio o 0,239 s na ścieżce wokalu i o 0,508 s na pełnym miksie — zgodność niemal o połowę gorsza. Dlatego do podświetlania po znakach (KTV/napisy) warto to włączyć. (Dokładny zysk jest właśnie mierzony ponownie na nowym silniku.)
2. Podaj pełny tekst: cały utwór, wiersz po wierszu, jeden do jednego z dźwiękiem. Brakująca fraza lub sekcja przesuwa wszystkie kolejne wiersze; nie wpisuj w tekst znaczników typu [00:23.82] (są automatycznie ignorowane).
3. W utworze platformy wystarczy vocal_separate: true, a my zrobimy „rozdzielenie + wyrównanie" w jednym kroku.

Trzy sposoby użycia

Jak wiążą się parametry (tu najczęściej się myli — przeczytaj uważnie)

• Wysyłasz song_id → ścieżka utworu platformy: nie wysyłaj dodatkowo lyrics / audio_url / audio_object_key;
• Wysyłasz audio_url albo audio_object_key → ścieżka utworu zewnętrznego: tylko jedno z dwóch, i nie wysyłaj song_id;
• vocal_separate działa tylko w utworach platformy; w utworze zewnętrznym zostanie odrzucone (dźwięk nie jest u nas, nie da się rozdzielić).

Nowość: bezpośrednie przesłanie pliku lokalnego (dźwięk nie przechodzi przez nasze serwery)

Użyj tego, gdy dźwięk jest na Twojej maszynie, a nie chcesz najpierw wrzucać go do własnego publicznego magazynu. Dwa kroki:

1. POST /api/music/lyrics-align/upload-ticket z file_name / file_size / content_type i otrzymujesz put_url (podpisany URL bez długoterminowych poświadczeń) oraz object_key;
2. Wyślij plik metodą PUT na put_url, przekazując content_type z odpowiedzi dokładnie taki, jaki jest (bierze udział w podpisie; jeden zmieniony znak to 403);
3. Przy wysyłaniu wyrównania podaj audio_object_key zamiast audio_url.

Poświadczenie jest jednorazowe: po zakończeniu wyrównania (sukces lub błąd) serwer usuwa obiekt, a ponowne użycie tego samego klucza daje błąd.

Nowość: tekst stał się opcjonalny

Wcześniej utwór zewnętrzny wymagał tekstu. Teraz możesz go pominąć: serwer najpierw wykonuje rozpoznanie i używa rozpoznanego tekstu jako tekstu utworu.

Trzeba to powiedzieć wprost: tekst zależy wtedy od wyniku rozpoznania, więc pojedyncze znaki mogą być błędne. Takie odpowiedzi są oznaczone lyrics_source: "asr", confidence: "low" oraz w warnings[] {"code":"no_reference_lyrics"}.

Do podświetlania po znakach / KTV zawsze podawaj oryginalny tekst.

Parametry żądania

Headers

Parametry treści

Ograniczenia

Przykłady żądania

Utwór zewnętrzny (tekst + adres dźwięku)

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": "Idę wśród chłodnych ulic\nNocny wiatr muska moje oczy\nCzas płynie jak woda",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

Utwór platformy (bez rozdzielania)

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

Utwór platformy + separacja wokalu (zalecane do karaoke)

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

Odpowiedź

Odpowiedź sukcesu

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "Idę wśród chłodnych ulic",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "I", "start": 21.66, "end": 21.74, "word": true},
        {"char": "d", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

Opis pól

Jak używać coverage (trzy progi)

Stan i czasy

Limit jednego przebiegu na serwerze to 8 minut; ustaw limit czasu klienta na 120 sekund lub więcej.

Odpowiedzi błędów

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

Zasada: brak wyniku końcowego to pełny zwrot. Opłata jest pobierana tylko wtedy, gdy znaczniki znaków naprawdę wrócą, a zwrot jest automatyczny, bez wniosku.

Rozliczenie

Złożenie:

do zapłaty = cena bazowa + (brak tekstu ? dopłata za transkrypcję : 0) + (zaznaczona separacja ? cena separacji : 0)

Opłata za separację wokalu jest pobierana tylko raz: jeśli utwór jest już rozdzielony i ścieżka wokalu jest dostępna, pobiera ją ten punkt końcowy; jeśli trzeba rozdzielać na miejscu, pobiera ją krok separacji.

Pełny przykład (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("jakość wyrównania coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # karaoke znak po znaku: każdy znak w line["chars"] ma własne start / end

Częste pytania

P: Wynik jest po znaku czy po wierszu? O: Jedno i drugie. lines[].start to poziom wiersza, lines[].chars[].start / end to poziom znaku; odtwarzacz bierze, co potrzebuje.

P: Dlaczego zwrócony tekst jest identyczny z wysłanym? O: Tak to zaprojektowano. Nie rozpoznajemy i nie przepisujemy, tylko wyrównujemy czas, więc tekst nigdy nie „zamieni się w literówkę".

P: coverage jest wysoki, a mimo to brzmi trochę przesunięte. O: Błąd po znaku to zwykle dziesiątki milisekund; jeśli cały utwór jest przesunięty o stałą wartość, najpewniej na początku dźwięku jest cisza — przytnij ją i spróbuj ponownie.

P: Dlaczego przed chwilą separacja działała, a teraz komunikat „ścieżka wokalu niedostępna"? O: Wyniki separacji to krótkotrwałe adresy tymczasowe (z pomiarów: wygasają po około pół godzinie). Wtedy punkt końcowy próbuje rozdzielić ponownie; jeśli nadal się nie uda, jest pełny zwrot. Czyli „rozdziel teraz, kalibruj później" jest zawodne — rób oba kroki w jednym przepływie.

P: Czy muszę sam rozdzielać utwór platformy? O: Nie. Przy vocal_separate: true sprawdzamy, czy utwór ma już ścieżkę wokalu; jeśli nie ma użytecznej, zwracamy błąd i pieniądze, a nie podsuwamy pełnego miksu.

P: Da się partiami? O: Jeden utwór na żądanie. Dla partii rób pętlę; każde wywołanie jest normalnie rozliczane, więc warto cache'ować wyniki.

P: Czy wynik jest zapisywany? O: Ten punkt końcowy nic nie zapisuje; zachowaj zwróconą wartość samodzielnie (znaczniki wierszy i znaków są w odpowiedzi).