API zur Kalibrierung von Songtext-Zeitstempeln

Aktualisiert am 2026-09-18 · Suno-API-Team

Das ist keine Spracherkennung. Der Text übernimmt immer den Songtext, den Sie liefern; wir setzen nur jedes Zeichen an den richtigen Zeitpunkt — deshalb kann es nie passieren, dass „falsch gehörte Zeichen den Text verschieben".

Beschreibung des Endpunkts

Er richtet vorhandenen Songtext am Audio aus und liefert Zeitstempel pro Zeile und pro Zeichen — für Karaoke-Zeichenhervorhebung, mitscrollenden Text und Untertitel.

Endpunkt: POST /api/music/lyrics-align

Authentifizierung: siehe Authentifizierung; der Header lautet Authorization: Bearer YOUR_API_KEY

Abrechnung: pro Aufruf (derzeit standardmäßig 0,1 ¥ pro Aufruf); ist bei einem Plattform-Song die Stimmseparatierung angehakt, wird zusätzlich einmal der Preis „Stimme/Begleitung trennen" der Plattform berechnet. Der tatsächlich berechnete Betrag folgt der Preis-Konfiguration im Backoffice.

Durchschnittsdauer: 5–15 Sekunden (je nach Audiolänge und ob die Stimme vor Ort getrennt werden muss)

Warum kalibriert werden muss: Zeitstempel der Generierungsseite sind nicht immer exakt

Die API für zeitgestempelte Songtexte liefert direkt die Wort-für-Wort-Zeitstempel der Generierungsseite, und sie sind ungenau:

• Wiederholungen, dichte Harmonien, Rap und lange Töne driften oft insgesamt oder verschieben einzelne Zeichen;
• manchen Songs fehlt ein Stück am Anfang (etwa ein reines Intro, dessen erster Abschnitt erst in der Mitte der ersten Minute beginnt);
• manche Zeilen lassen sich schlecht an einen klaren Zeitanker binden.

Die Kalibrierung macht die Zeitausrichtung auf Basis Ihres eigenen Songtexts neu: nur die Zeit wird korrigiert, nie der Text — passend für Fälle, in denen „passt es genau" zählt (KTV-Zeichenhervorhebung, Zeichen-Untertitel, Mitsing-Bewertung).

Empfohlenes Vorgehen (drei Schritte, beste Ergebnisse)

1. Zuerst die Stimme extrahieren (Stimme/Begleitung trennen) und nur die Stimmspur ausrichten — Begleitung und Harmonien stören dann nicht mehr. Messgrundlage: im Zeilenvergleich „Vollmix vs. Stimmspur" desselben Songs unterschieden sich 5 von 28 Zeilen um mehr als 0,25 s (die größte um 2,64 s); zwei unabhängige Motoren wichen auf der Stimmspur im Mittel um 0,239 s und auf dem Vollmix um 0,508 s ab — fast halb so viel Übereinstimmung. Für Zeichenhervorhebung (KTV/Untertitel) empfiehlt sich daher, sie einzuschalten. (Der genaue Gewinn wird mit dem neuen Motor neu gemessen.)
2. Vollständigen Songtext liefern: den ganzen Song, Zeile für Zeile, eins zu eins zum Audio. Eine fehlende Zeile oder Passage verschiebt alle folgenden Zeilen; schreiben Sie keine Zeitstempel wie [00:23.82] in den Text (sie werden automatisch ignoriert).
3. Bei einem Plattform-Song genügt vocal_separate: true, und wir erledigen „Trennen + Ausrichten" in einem Schritt.

Drei Nutzungsarten

Wie die Parameter zusammenhängen (hier passieren die meisten Fehler — bitte genau lesen)

• song_id senden → Plattform-Song: senden Sie nicht zusätzlich lyrics / audio_url / audio_object_key;
• audio_url oder audio_object_key senden → externer Song: nur eines von beiden, und kein song_id;
• vocal_separate wirkt nur bei Plattform-Songs; bei einem externen Song wird es abgelehnt (das Audio liegt nicht bei uns, es kann nicht getrennt werden).

Neu: direkter Upload einer lokalen Datei (das Audio läuft nicht über unsere Server)

Nutzen Sie das, wenn das Audio auf Ihrem Rechner liegt und Sie es nicht erst in Ihren eigenen öffentlichen Speicher legen möchten. Zwei Schritte:

1. POST /api/music/lyrics-align/upload-ticket mit file_name / file_size / content_type liefert eine put_url (signierte URL ohne langlebige Zugangsdaten) und einen object_key;
2. Laden Sie die Datei per PUT auf put_url und übernehmen Sie den content_type aus der Antwort unverändert (er ist Teil der Signatur; ein geändertes Zeichen ergibt 403);
3. Senden Sie beim Ausrichten audio_object_key statt audio_url.

Die Zugangsdaten sind einmalig: nach dem Ausrichten (Erfolg oder Fehler) löscht der Server das Objekt, und derselbe Key führt zu einem Fehler.

Neu: der Songtext ist jetzt optional

Früher war bei externen Songs Text Pflicht. Jetzt kann er fehlen: der Server führt eine Erkennung aus und nutzt den erkannten Text als Songtext.

Der Preis dafür muss klar sein: der Text richtet sich dann nach dem Erkennungsergebnis, einzelne Zeichen können falsch sein. Solche Antworten sind gekennzeichnet mit lyrics_source: "asr", confidence: "low" und in warnings[] {"code":"no_reference_lyrics"}.

Für Zeichenhervorhebung / KTV liefern Sie bitte immer den Originaltext.

Anfrageparameter

Headers

Body-Parameter

Grenzen

Beispielanfragen

Externer Song (Text + Audioadresse)

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": "Ich gehe durch die kalten Straßen\nDer Nachtwind streift meine Augen\nDie Zeit fließt wie das Wasser",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

Plattform-Song (ohne Trennung)

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

Plattform-Song + Stimmseparatierung (für Karaoke empfohlen)

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

Antwort

Erfolgsantwort

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "Ich gehe durch die kalten Straßen",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "I", "start": 21.66, "end": 21.74, "word": true},
        {"char": "c", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

Feldreferenz

Wie coverage zu nutzen ist (drei Stufen)

Status und Laufzeiten

Das Limit eines Serverlaufs beträgt 8 Minuten; setzen Sie den Client-Timeout auf 120 Sekunden oder mehr.

Fehlerantworten

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

Grundsatz: ohne Endergebnis volle Erstattung. Berechnet wird erst, wenn tatsächlich Zeichen-Zeitstempel zurückkommen, und die Erstattung läuft automatisch, ohne Antrag.

Abrechnung

Die Kombination:

zu zahlen = Basispreis + (kein Text geliefert ? Transkriptionszuschlag : 0) + (Trennung angehakt ? Trennungspreis : 0)

Die Trennkosten fallen nur einmal an: haben Sie den Song schon getrennt und die Stimmspur liegt direkt vor, berechnet sie dieser Endpunkt; muss vor Ort getrennt werden, berechnet sie der Trennungsschritt.

Vollständiges Beispiel (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("Ausrichtungsqualität coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # Zeichen-Karaoke: jedes Zeichen in line["chars"] hat eigenes start / end

Häufige Fragen

F: Ist die Ausgabe pro Zeichen oder pro Zeile? A: Beides. lines[].start ist pro Zeile, lines[].chars[].start / end pro Zeichen; der Player nimmt, was er braucht.

F: Warum ist der zurückgegebene Text identisch mit meinem? A: Das ist so gewollt. Wir erkennen nicht um und schreiben nicht um, wir richten nur die Zeit aus — der Text kann also nie „in Tippfehler korrigiert" werden.

F: coverage ist hoch, es klingt aber trotzdem leicht versetzt. A: Der Zeichenfehler liegt meist im Bereich von Zehntel Millisekunden bis einigen Dutzend Millisekunden; ist der ganze Song um einen festen Wert versetzt, liegt am Anfang des Audios wahrscheinlich eine Stille — schneiden Sie sie ab und versuchen Sie es erneut.

F: Warum ging die Trennung gerade noch, und jetzt heißt es „Stimmspur nicht verfügbar"? A: Trennergebnisse sind kurzlebige temporäre Adressen (gemessen: Ablauf nach etwa einer halben Stunde). Dann versucht der Endpunkt automatisch erneut zu trennen; scheitert das ebenfalls, gibt es volle Erstattung. „Erst trennen, später kalibrieren" ist also unzuverlässig — machen Sie beides im selben Ablauf.

F: Muss ich einen Plattform-Song selbst vorher trennen? A: Nein. Mit vocal_separate: true prüfen wir, ob der Song bereits eine Stimmspur hat; gibt es keine nutzbare, melden wir einen Fehler und erstatten, statt den Vollmix durchzureichen.

F: Geht das in Stapeln? A: Ein Song pro Anfrage. Für Stapel schleifen Sie; jeder Aufruf wird normal berechnet, daher empfiehlt sich lokales Caching.

F: Wird das Ergebnis gespeichert? A: Dieser Endpunkt persistiert nichts; speichern Sie den Rückgabewert selbst (Zeilen- und Zeichen-Zeitstempel stehen in der Antwort).