API für Sprachgenerierung (Speech)

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

Beschreibung des Endpunkts

Speech verwandelt eine Rede oder eine einzeilige Beschreibung in „Sprech-/Rede"-Audio, optional mit Hintergrundmusik. Es passt für Reden, Trinksprüche, Narration, Voice-over-Skripte, Audioinhalte und ähnliche Szenarien.

Bitte beachten: Dieser Endpunkt erzeugt Sprech-Audio, keinen gesungenen Song (keine Melodie, kein gesungener Gesang). Wenn Sie Gesang brauchen, nutzen Sie die Generierungs-API im einfachen Modus oder die Generierungs-API im benutzerdefinierten Modus.

Endpunkt: POST /api/music/speech

Abrechnung: Kostenpflichtig, derzeit standardmäßig 0,6 ¥ pro Aufruf. Jeder Aufruf liefert meist 2 Audios; der tatsächlich berechnete Betrag folgt der Preis-Konfiguration im Backoffice.

Max Mode / Variety: Dieser Endpunkt unterstützt die optionalen Parameter max_mode und variety (0-4). Mit aktiviertem max_mode wird dieser Aufruf zum doppelten Preis abgerechnet (0,6 → 1,2 ¥ pro Aufruf); variety kostet nichts extra. Bedeutung und Schreibweise stehen im Abschnitt „Erweiterte Parameter“ in der Übersicht der neuen API.

Wartezeiten und Timeouts (wichtig): Dies ist ein synchroner Endpunkt — die Bestellung wird erst angenommen und der Generierung übergeben, wenn die Antwort eintrifft. Gemessen antworten die meisten Anfragen innerhalb von Sekunden (1–10 s); wie bei anderen synchronen Generierungsendpunkten kann es in Extremfällen aber länger dauern. Setzen Sie den Client-Timeout auf 300 Sekunden oder mehr; keine Antwort bedeutet nicht, dass nichts generiert wurde, und wiederholen Sie nicht direkt nach einem Timeout (das dupliziert die Bestellung und berechnet erneut). Wenn die Verbindung abbrach, prüfen Sie später mit GET /api/music/songs. Siehe „Wartezeiten und Timeout-Einstellungen“ in der Übersicht der neuen API.

Inhaltliche Konformität: Die Plattform prüft die Rede auf Urheberrecht und Inhaltsrichtlinien. Wird sie als urheberrechtlich geschütztes Material eingestuft (etwa das Zitieren fremder Songtexte oder der wörtliche Text eines bekannten Werks), schlägt dieser Aufruf fehl und der volle Betrag wird automatisch erstattet. Wechseln Sie zu Ihrer eigenen Formulierung oder wandeln Sie das Zitat in eine Umschreibung um und versuchen Sie es erneut.

Anfrageparameter

Headers

Body-Parameter

Dieser Endpunkt unterstützt kein duration: Werden sie gesendet, kommt HTTP 400 zurück, es wird nicht stillschweigend ignoriert. Die Länge der Rede ergibt sich aus der Textlänge von script.

Beispielanfragen

Minimale Anfrage (nur der Text)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Guten Morgen allerseits! Mein Thema heute ist, unsere Zeit gut zu nutzen und voranzugehen."
  }'

Vollständige Anfrage (mit Ton, Geschlecht und ausgeschalteter Hintergrundmusik)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Python-Beispiel

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Guten Nachmittag, liebe Kolleginnen und Kollegen. Ich berichte über den Fortschritt dieser Woche.',
        'tone': 'ruhig und klar, Besprechungsbericht',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # meist 2 Einträge
for item in items:
    print(item['song_id'], item['status'])

Hinweise zu den Parametern

script (die Rede, erforderlich)

• Fügen Sie den Inhalt ein, den Sie vortragen wollen; Sie können auch nur eine Beschreibung schreiben und das Modell die Rede verfassen lassen (zum Beispiel „eine Halbzeitansprache für ein Team, das zwanzig Punkte zurückliegt, vom leisen Murmeln bis zum Brüllen aus voller Kehle“).
• Zeilenumbrüche, Absätze und Bühnenanweisungen wie [Pause] können direkt geschrieben werden, und das Modell folgt ihnen so weit wie möglich.
• Die Grenze liegt bei 3000 Zeichen (gezählt in Unicode-Zeichen; ein chinesisches Schriftzeichen zählt als 1); darüber kommt 400 und es wird nichts berechnet.

tone (Ton und Szene, optional)

Er beschreibt, wie gesprochen wird, nicht was gesagt wird. Sinnvoll sind vier Arten von Angaben: Ton, Tempo/Rhythmus, Emotion und Ort.

Energiegeladen und kraftvoll, Tempo von langsam zu schnell, deutliche Pausen; Schulaula, vor allen Schülerinnen und Schülern
Warm und weich, ruhiges Tempo; Hochzeitsempfang
Gelassen und zurückhaltend, gleichmäßig und klar; Bericht an den Vorstand

Die Grenze liegt bei 1000 Zeichen. Wird nichts gesendet, leitet das Modell es aus dem Inhalt von script ab.

gender / vocal_gender (Geschlecht der sprechenden Person, optional)

• Für eine männliche Stimme m oder male senden, für eine weibliche f oder female; der Server normalisiert auf m / f.
• Beide Feldnamen funktionieren — nutzen Sie nur einen: gender ist die empfohlene Form für diesen Endpunkt; wenn Sie bereits den benutzerdefinierten Modus verwenden, können Sie vocal_gender beibehalten.
• Weglassen bedeutet „beliebig“, und das Modell entscheidet.

backing_music (Hintergrundmusik, optional)

• Standard ist true (mit Hintergrundmusik), wie in der Suno-Webversion.
• false ergibt eine Rede nur mit Stimme — praktisch, wenn Sie später eigene Musik oder Sprecher ergänzen wollen.
• Muss ein JSON-Boolescher Wert true / false sein; die Strings "true" und "1" werden ebenfalls akzeptiert, Booleans sind aber empfohlen.

model (Modell, optional)

Alle drei Kundenmodelle sind verfügbar und gleich teuer (0,6 ¥ pro Aufruf). Die Rede wird von der Suno-v6-Familie erzeugt; ohne Angabe wird sie als suno-v6 behandelt. Ohne besondere Vorliebe ist dieses Feld normalerweise nicht nötig.

Parametervalidierung und Textgrenzen

Die folgenden Fälle liefern HTTP 400, und alle werden vor der Abrechnung abgefangen, es entstehen also keine Kosten:

Grenzen der Textfelder

Zu lange Texte liefern ebenfalls HTTP 400 und starten keine Generierung und keine Vorabberechnung. Gezählt wird in Unicode-Zeichen (ein chinesisches Schriftzeichen zählt als 1), führende und abschließende Leerzeichen inklusive:

Die Fehlermeldung sieht so aus: script must not exceed 3000 characters; received 4120. Das erste Wort ist das Feld, das die Grenze überschritt, und am Ende steht die tatsächliche Anzahl — bei einem 400 können Sie also direkt mit diesen zwei Zahlen kürzen.

Antwort

Die Antwort ist ein Song-Array, exakt wie bei den anderen Generierungsendpunkten (meist 2 Einträge). Speichern Sie die song_id und prüfen Sie mit der API zum Abfragen von Songs und zum Verlauf den Endstatus und die Audioadresse:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Die Zeit gut nutzen",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Fehlgeschlagene Generierung und Erstattungen

Schlägt die Generierung fehl, wird der Betrag für diesen Aufruf automatisch vollständig erstattet; ein Kontakt zum Support ist nicht nötig. Der Grund steht in der Antwort oder im error_message der API zum Abfragen von Songs und zum Verlauf.

Die häufigste Ursache ist eine Einstufung als urheberrechtlich geschütztes Material, zum Beispiel:

Your lyrics contain copyrighted material. Please change it and try again.

Ersetzen Sie in diesem Fall den Text durch Ihre eigene Formulierung (oder wandeln Sie das Zitat in eine Umschreibung um) und reichen Sie ihn erneut ein.

Häufige Fragen

F: Warum ist das Ergebnis „Sprechen" und nicht Gesang? A: Dies ist der Rede-Endpunkt, seine Ausgabe ist Sprech-Audio. Für Gesang nutzen Sie die Generierungs- bzw. benutzerdefinierten Endpunkte.

F: Warum kommen jedes Mal 2 Einträge? A: Wie bei den anderen Generierungsendpunkten der Plattform erzeugt eine Generierung 2 Kandidaten; fragen Sie sie getrennt über song_id ab und behalten Sie den passenden.

F: Wie steuere ich die Länge? A: Sie ergibt sich aus der Länge von script; dieser Endpunkt akzeptiert keinen duration-Parameter.

F: Kann ich eine Stimme angeben (zum Beispiel meine geklonte Stimme)? A: Die aktuelle Version unterstützt das nicht. Die Rede nutzt einen festen Satz an Redestimmen, und gender wählt männlich oder weiblich; wenn Sie Ihre eigene Stimme brauchen, nutzen Sie die entsprechende Funktion der API zum Anlegen eines Sprachprofils (empfohlen).

F: Was passiert, wenn ich tone nicht sende? A: Das Modell leitet Ton und Rhythmus aus dem Inhalt von script ab. Um einen Stil zuverlässig zu reproduzieren, schreiben Sie Ton, Tempo und Ort in tone.

Kompatible Felder

Verwenden Sie bei neuen Integrationen durchgängig snake_case. Die übrigen Felder (script, tone, song_title, backing_music) haben keine camelCase-Aliase.

Nächste Schritte

Sobald Sie die song_id haben:

1. Prüfen Sie mit der API zum Abfragen von Songs und zum Verlauf den Generierungsstatus und die Audioadresse;
2. Laden Sie das Ergebnis nach der Fertigstellung mit der API zum Herunterladen und Anhören von Song-Medien herunter oder hören Sie hinein;
3. Für Stapel-Downloads oder das Kopieren in Ihren eigenen Speicher siehe die Endpunkte des Download-Centers.