Suno API Dokumentation – Überblick

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

Registrierung per E-Mail genügt, um einen API-Schlüssel zu erstellen. Eine Generierung kostet 0,6 ¥ und liefert 2 Songs, inklusive MP3/WAV-Download, Covers, Extend, Stem-Trennung und Voice-Cloning. Basis-URL: https://www.suno-api.io.

Diese Seite beschreibt die aktuell verfügbaren Modelle, alle Generierungs- und Bearbeitungs-Endpunkte, die Abrechnung und die empfohlene Lesereihenfolge. Bei einer ersten Integration lesen Sie sie von oben nach unten; die Einstiegspunkte zur Fehlersuche bei 401/403/429 stehen ebenfalls hier.

Kurze Antworten

Wie bekomme ich einen API-Schlüssel? Mit einer E-Mail-Adresse registrieren, die Konsole öffnen, zur Token-Verwaltung gehen und ein Token anlegen. Telefonnummer und Kreditkarte sind nicht nötig.

Was kostet ein Aufruf? Eine Generierung kostet 0,6 ¥ und liefert 2 Songs. Statusabfragen, WAV, zeitgestempelte Songtexte und Prompt-Vorschläge sind kostenlos.

Welche Modelle werden unterstützt? suno-v6 (Standard), suno-v6-wild und suno-v6-mini. Die Standard-Generierungsmodelle v5.5 und älter wurden abgeschaltet; bestehende Werke sind nicht betroffen.

Wie lautet die Basis-URL? https://www.suno-api.io, mit dem Header Authorization: Bearer YOUR_API_KEY.

Aktuell verfügbare Modelle

Für die normale Songgenerierung kann der Kunde nur suno-v6, suno-v6-wild und suno-v6-mini angeben. Wird model weggelassen, wird suno-v6 verwendet.

Die Standardmodelle suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 und suno-v5-5 wurden abgeschaltet. In historischen Aufgaben können diese Namen noch auftauchen; das sind historische Daten und kein Beleg dafür, dass das Modell für neue Anfragen nutzbar ist. Eine Ausnahme ist die Stem-Trennung – siehe Stems (Trennung von Gesang/Begleitung).

Authentifizierung

Alle öffentlichen API-Schlüssel-Endpunkte verwenden dieselben Header:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Basis-URL:

https://www.suno-api.io

Allgemeine Parameterregeln

• Eine number im Request-Body muss eine JSON-Zahl sein, niemals ein Prozent-String. Eine Intensität von 50 % wird 0.5 geschrieben, nie 50 oder 50%.
• Ein boolean muss true oder false sein. Senden Sie keine Ersatzwerte wie true, false, 0 oder 1.
• Mit „nein" markierte Felder dürfen ganz entfallen. Wenn Sie sich bei einem Parameter unsicher sind, lassen Sie ihn weg und überlassen Sie dem Dienst sein Standardverhalten; senden Sie nicht leere Zeichenkette, null oder 0 statt „nicht gesendet", denn 0 ist bei einigen Zahlenfeldern ein gültiger Wert.
• Feldnamen sind schreibungsabhängig. Jede Endpunktseite nennt das empfohlene Feld und die kompatiblen Aliasse; senden Sie sie genau wie in der Tabelle. Wo snake_case und camelCase laut Dokumentation beide erlaubt sind, senden Sie nicht beide gleichzeitig.
• Alle Dauerfelder auf _s oder Seconds sind Sekunden und erlauben Dezimalwerte. Unix-Zeitstempel sind gesondert beschrieben, einschließlich Sekunden oder Millisekunden.
• Eine ID, die mit pending: beginnt, ist ein Platzhalter der Plattform, keine echte Song-ID. Verwenden Sie sie nur dort, wo der Endpunkt das ausdrücklich dokumentiert; sonst warten Sie auf die echte song_id.

Obergrenzen für Textfelder

Überschreitungen liefern direkt HTTP 400: es wird nichts generiert, nichts vorab berechnet und kein Aufgaben-Datensatz angelegt. Gezählt wird in Unicode-Zeichen (ein Schriftzeichen zählt als 1); führende und nachfolgende Leerzeichen zählen mit.

Die message nennt das betroffene Feld und die gemessene Länge – mit diesen beiden Zahlen lässt sich der Text direkt kürzen:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Betrifft: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Eine Ausnahme: description bei POST /api/music/sounds ist auf 100 Zeichen begrenzt, weil der Effektklang-Pfad die kürzere Grenze der Plattform nutzt.

Asynchrone Generierung und Audio-Adressen

Musikgenerierungs-Endpunkte arbeiten standardmäßig asynchron. Wenn die erste Antwort status gleich pending, submitted oder processing enthält, sind leere audio_url, video_url oder cover_url normal und bedeuten keinen Fehlschlag. Speichern Sie die echte song_id (oder die zurückgegebene client_request_id) und fragen Sie den passenden Endpunkt ab; Audio-Adressen erst lesen und herunterladen, wenn der Status abgeschlossen ist.

⚠️ Audio-Adressen laufen nach 7 Tagen ab – Dateien rechtzeitig übertragen

audio_url, wav_url, video_url und die von den Download-Endpunkten zurückgegebenen Adressen kommen aus dem Objektspeicher der Plattform und laufen standardmäßig nach 7 Tagen ab (Dateien werden recycelt; eine alte Adresse liefert 404 / schlägt beim Download fehl).

• Verschieben Sie die Dateien innerhalb dieser 7 Tage in Ihren eigenen Speicher (eigener Objektspeicher, CDN oder Serverplatte). Behandeln Sie unsere Adressen nicht als langfristige Links.
• Eine abgelaufene Adresse erfordert keine Neugenerierung und kostet nichts extra: rufen Sie die Song-Abfrage-API (oder die Medien-Download-API) erneut auf und Sie erhalten eine neue gültige Adresse.

Wartezeiten und Timeout-Einstellungen

Generierungs-Endpunkte sind synchron: Die Bestellung gilt erst mit dem Eintreffen der Antwort als angenommen und an die Plattform übergeben. Vorher muss der Dienst ein Konto einplanen und die nötige Sicherheitsprüfung bestehen – es gibt keine Zwischenantwort, und kein anderer Endpunkt sieht die Bestellung. Der einzige verlässliche Beleg dafür, dass „etwas generiert wurde", ist also die Antwort selbst, nicht das, was man während des Wartens beobachtet.

Gemessene Wartezeiten (Produktion, /api/music/create-Familie, 18.–20.09.2026)

• Rund 10 % der Anfragen brauchen länger als 30 Sekunden, rund 1 % 1–2 Minuten. Eine langsame Anfrage bedeutet meist, dass diesmal zuerst eine Sicherheitsprüfung nötig war.
• Anfragefelder, Antwortform, Fehlercodes und Abrechnung sind unverändert, bestehende Integrationen müssen nur das Client-Timeout erhöhen – keine weitere Codeänderung.

Anforderungen an die Integration

1. Setzen Sie das Client-Timeout auf 300 Sekunden oder mehr. Clients mit 30, 60 oder 120 Sekunden trennen die Verbindung während des Wartens.
2. Keine Antwort heißt nicht, dass nichts generiert wurde. Bei Timeout oder abgebrochener Verbindung kann die Bestellung bereits angenommen sein und generieren.
3. Nach einem Timeout nicht sofort erneut senden: eine doppelte Übermittlung erzeugt eine zweite Bestellung und berechnet erneut.
4. Wurde die Verbindung getrennt, listen Sie Ihre Songs etwas später mit GET /api/music/songs (neueste zuerst) – angenommene Bestellungen erscheinen normal. Erst nach Bestätigung, dass die Bestellung fehlt, erneut senden.
5. Bei einer Störungsmeldung bitte den Antwort-Header X-Oneapi-Request-Id beilegen, damit genau diese Anfrage gefunden werden kann.

Keine lange Verbindung gewünscht? Nutzen Sie den Empfangsbeleg-Modus. POST /api/music/create und POST /api/music/create/custom unterstützen einen optionalen Empfangsbeleg: "accept_mode": "async" im Body (oder der Header X-Accept-Mode: async) lässt den Endpunkt sofort 202 mit einer Belegnummer zurückgeben, während die Generierung im Hintergrund weiterläuft; den Fortschritt liefert GET /api/music/requests/{request_id}. Ein Client mit nur wenigen Dutzend Sekunden Timeout kann „keine Antwort" dann nicht mehr als „nichts generiert" fehldeuten und auch nicht doppelt durch Wiederholungen berechnen. Siehe „Empfangsbeleg-Modus" in der API für die Generierung im einfachen Modus.

Zur Referenz: python requests nutzt timeout=300, urllib nutzt urlopen(..., timeout=300), Node nutzt req.setTimeout(300000), curl nutzt --max-time 300.

Empfohlene Endpunktliste

Die Endpunkte /api/voice/clone/* und /api/music/generate-with-voice gehören zur frühen Voice-Cloning-Kette und werden für neue Integrationen nicht empfohlen; nutzen Sie stattdessen die 【Empfohlen】 Sprachprofil-API.

Erweiterte Parameter: Max Mode und Variety

Generierungs-Endpunkte unterstützen diese beiden optionalen Parameter (weglassen behält Verhalten und Preis bei):

Unterstützt von: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• Der doppelte Preis in der Praxis: ein Endpunkt mit 0,6 ¥ pro Aufruf kostet mit max_mode 1,2 ¥; mit gewählter Stimme generieren kostet 1,2 ¥ pro Aufruf und 2,4 ¥ mit Max Mode; das Voice-Cover der 【Empfohlen】 Sprachprofil-API kostet ebenfalls 1,2 ¥ pro Aufruf (2,4 ¥ mit max_mode).
• variety gilt nur für die suno-v6-Familie (suno-v6, suno-v6-wild, suno-v6-mini); bei anderen Modellen liefert das Senden 400.
• Soundeffekte, Stems, Concat, WAV und die Studio-Bearbeitungen (Zuschneiden, Abschnitt entfernen, Fade, Rückwärts, Geschwindigkeit usw.) kennen diese Parameter nicht — explizites Senden liefert 400, damit ein Parameter nie stillschweigend ignoriert wird.
• variety ist der ganzzahlige Wert 0-4; style_weight und weirdness_constraint sind Dezimalwerte von 0 bis 1, die Skalen unterscheiden sich also.

Gemeinsame Antwortfelder von Songs

Generierungs-, Cover-, Extend-, Trennungs- und Abfrage-Endpunkte liefern in der Regel ein Array von Songs mit diesen Feldern:

Vier Schritte zur Integration (Minimalbeispiel)

Mit diesen vier Schritten erhalten Sie Ihren ersten Song; die vollständigen Felder je Schritt stehen auf der passenden Seite der empfohlenen Endpunktliste.

# 1) Generierung absenden: 0,6 ¥, liefert 2 Songs
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright German pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Abfragen, bis status completed ist (3–5 Sekunden ist ein guter Abstand)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "die in Schritt 1 zurückgegebene song_id"}'

# 3) Medienadresse holen: Lese-Endpunkte sind kostenlos; song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "dieselbe song_id", "kind": "song"}'

Bei Problemen: 401 / 402 / 403 / 429 in der Fehlerübersicht; Timeouts und Doppelberechnungen im Abschnitt „Wartezeiten und Timeout-Einstellungen"; Details je Endpunkt in der Liste unten.

Empfehlungen

• Neue Integrationen sollten durchgängig suno-v6 verwenden.
• Bei Endpunkten mit Standardpreis richtet sich der tatsächlich berechnete Betrag nach der aktuellen Preisverwaltung und dem angefragten Modell.
• Generierungs-Endpunkte liefern zuerst eine Aufgabe; das fertige Audio holen Sie über /api/music/query.
• wait_completion=true blockiert bis zum Ende und eignet sich für Tests mit geringem Volumen; in der Produktion ist Polling besser.
• Generierungs-Endpunkte können lange brauchen — setzen Sie das Client-Timeout auf 300 Sekunden oder mehr und beachten Sie, dass „keine Antwort" nicht „nichts generiert" bedeutet.
• Upload, Cover, Ersetzen und WAV hängen von Plattformkonten und Rechten am Quell-Clip ab; bei Fehlern zuerst message oder error_message lesen.

Zu dieser Dokumentation

Diese Seite wurde entlang der tatsächlich von der Create UI angebundenen Funktionen neu geordnet; neue Integrationen sollten hier beginnen. Die ältere API-Dokumentation bleibt im Abschnitt „Ältere API-Dokumentation (kompatibel)" für alle, die ihr bisheriges Vorgehen beibehalten wollen.