Generierungs-API im benutzerdefinierten Modus

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

Beschreibung des Endpunkts

Der benutzerdefinierte Modus passt, wenn Text, Stil und Titel bereits fertig sind und Sie die singende Stimme, die Stärke des Stileinflusses und den Grad der Zufälligkeit der Generierung steuern wollen.

Endpunkt: POST /api/music/create/custom

Abrechnung: Kostenpflichtig, derzeit standardmäßig 0,6 ¥ pro Aufruf. Jeder Aufruf liefert meist 2 Songs; der tatsächlich berechnete Betrag folgt der aktuellen 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 in 1-3 Sekunden, etwa 10 % brauchen länger als 30 Sekunden und die längste liegt bei rund 230 Sekunden. 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.

Anfrageparameter

Headers

Body-Parameter

Hinweise zu den erweiterten Parametern

Geschlecht der Stimme vocal_gender

• Senden Sie m oder male für eine männliche Stimme, f oder female für eine weibliche.
• Der Dienst normalisiert male und female zu m bzw. f.
• Mit instrumental=true wird kein Parameter für das Stimmgeschlecht an den Generierungsdienst gesendet.

Stileinfluss style_weight

Steuert, wie stark das Ergebnis style_tags folgt. Je höher der Wert, desto eher folgt das Ergebnis den angegebenen Stil-Tags.

Zufälligkeit weirdness_constraint

Steuert, wie stark das Ergebnis variiert und experimentiert. Höhere Werte ergeben meist mehr Variation; niedrigere Werte ein sichereres Ergebnis.

Beide Zahlenparameter liegen zwischen 0.0 und 1.0, und 0 ist ein gültiger ausdrücklicher Wert. Nur das vollständige Weglassen des Felds bedeutet „nicht angegeben“.

Beachten Sie beim Ausfüllen, dass es sich um Dezimalbrüche handelt, nicht um Prozent-Ganzzahlen. Orientierung: 0.0 bis 0.3 ist konservativ, 0.4 bis 0.6 ausgewogen, 0.7 bis 1.0 experimenteller; ohne klare Vorliebe nehmen Sie 0.5 oder lassen die Felder einfach weg. Beispiel: weirdness_constraint: 0.5, niemals 50 oder 50%.

Mit instrumental=true entsteht ein Instrumental, daher wirken Text und Stimmgeschlecht nicht wie bei einem gesungenen Song; wenn Sie Gesang brauchen, senden Sie false oder lassen Sie das Feld weg. Boolesche Felder müssen JSON-true/false verwenden, keine Zeichenketten.

Python-Beispielanfrage

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nDie Nacht fällt auf das Meer\nein Abendwind streift am Fenster vorbei',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Abendwind am Meer',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Empfangsbeleg-Modus (optional)

Dieser Endpunkt unterstützt auch den Empfangsbeleg-Modus der Generierungs-API im einfachen Modus: mit "accept_mode": "async" im Body (oder dem Header X-Accept-Mode: async) antwortet der Endpunkt sofort mit 202 und einer Belegnummer, die Generierung läuft im Hintergrund weiter, und Sie verfolgen den Fortschritt mit GET /api/music/requests/{request_id}.

Das passt zu Clients, die keine langen Verbindungen halten sollen oder nicht wollen, dass ein Timeout als „nichts generiert“ gelesen wird. Ohne diesen Parameter ist das Verhalten genau wie zuvor.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Abendwind am Meer",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

Antwortform und Abfragemethode stehen im Abschnitt „Empfangsbeleg-Modus“ der Generierungs-API im einfachen Modus.

Parametervalidierung

Diese Fälle liefern HTTP 400, und die message der Fehlermeldung nennt das ungültige Feld:

• style_weight oder weirdness_constraint ist keine Zahl.
• Ein Zahlenwert liegt unter 0.0 oder über 1.0.
• vocal_gender ist keiner von m, f, male, female.

Grenzen der Textfelder

Diese Felder liefern bei Überschreitung ebenfalls HTTP 400, gehen nie in die Generierung und werden nicht vorab berechnet. Gezählt wird in Unicode-Zeichen (ein Han-Zeichen zählt als 1), führende und abschließende Leerzeichen zählen mit:

Die Fehlermeldung sieht so aus: style_tags must not exceed 1000 characters; received 2772. Das erste Wort ist das betroffene Feld, am Ende steht die gemessene Anzahl, bei einem 400 kürzen Sie also mit diesen zwei Zahlen, statt Feld für Feld zu probieren. Die allgemeinen Regeln stehen in „Grenzen der Textfelder“ in der Übersicht der neuen API.

Antwort

Der Endpunkt liefert üblicherweise ein Array mit 2 Songs. Eine asynchrone Anfrage startet normalerweise in pending; speichern Sie die song_id und lesen Sie Endstatus und Audio-Adresse über die API zum Abfragen von Songs. Die Songfelder sind dieselben wie in der Generierungs-API im einfachen Modus.

Kompatible Felder

Neue Integrationen sollten durchgehend snake_case verwenden. Trägt eine Anfrage sowohl snake_case als auch camelCase, gewinnt der snake_case-Wert.