API zum Abfragen von Songs und zum Verlauf

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

Diese Seite behandelt drei kostenlose Abfrage-Endpunkte:

Wenn Sie bei einem Generierungs-Endpunkt den Empfangsbeleg-Modus (accept_mode=async) verwendet haben, halten Sie eine Belegnummer in der Hand, keine Song-ID. Verfolgen Sie den Fortschritt mit GET /api/music/requests/{request_id} und kehren Sie zu den Endpunkten dieser Seite zurück, sobald Sie die echte song_id haben. Siehe „Empfangsbeleg-Modus“ in der Generierungs-API im einfachen Modus.

Authentifizierung und Datenumfang

Alle drei Endpunkte authentifizieren sich mit demselben API-Schlüssel:

Authorization: Bearer YOUR_API_KEY

Der Song-Verlauf ist nach der user_id isoliert, zu der der API-Schlüssel gehört. Mehrere Schlüssel unter demselben Hauptkonto können den Verlauf dieses Kontos lesen, aber nicht den eines anderen Nutzers oder eines Subsite-Kontos.

Die Verlaufs-Endpunkte liefern nur tatsächlich generierte Songs. Ausgeschlossen sind:

• Platzhalter-Einträge der Generierung, die mit pending: beginnen;
• Uploads von Quell-Audio und Einträge des erweiterten Uploads;
• Teilergebnisse wie Gesangs-/Begleitungstrennung und Stems;
• Songs anderer Nutzer oder von Subsite-Konten.

1. Generierungsstatus abfragen

Fragt den aktuellen Status und das Endergebnis einer oder mehrerer Song-IDs ab.

Endpunkt: POST /api/music/query

Abrechnung: Kostenlos.

Headers

Body-Parameter

Beispielanfrage

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

Beispielantwort

[
  {
    "song_id": "clip_id_1",
    "song_title": "Songtitel",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Songtext",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Kompatibilitätshinweise

Ältere Dokumentation zeigt song_ids möglicherweise als Array. Heute wird eine kommagetrennte Zeichenkette empfohlen, was dem tatsächlichen Aufruf des Endpunkts entspricht.

song_ids muss echte Song-IDs enthalten. Eine Platzhalter-ID, die mit pending: beginnt, ist keine finale song_id und kann hier nicht verwendet werden; werden nur Platzhalter-IDs abgefragt, kann ein leeres Array [] zurückkommen.

model, model_version oder der Plattform-model_name einer Antwort können historische Werte behalten. Neue Aufgaben sollten suno-v6, suno-v6-wild oder suno-v6-mini verwenden; suno-v2 bis suno-v5-5 sind abgekündigt, und diese Namen im Verlauf zu sehen heißt nicht, dass das Modell weiterhin eingesetzt werden kann.

Solange eine Generierungsaufgabe pending, submitted oder processing ist, können audio_url, video_url und cover_url leer sein — das ist bei einer unfertigen Aufgabe normal. Schließen Sie nicht allein aus einer leeren Adresse auf einen Fehler; nutzen Sie status und fragen Sie erneut ab, sobald der Status abgeschlossen ist. Erst wenn der Status abgeschlossen ist und die Adressen weiterhin leer bleiben, sollten Sie den Support mit der song_id kontaktieren.

⚠️ Audio-Adressen gelten 7 Tage — übertragen Sie Ihre Dateien rechtzeitig

Die hier zurückgegebenen audio_url, video_url (und weitere Medienadressen wie WAV) werden aus dem Objektspeicher der Plattform geliefert und laufen standardmäßig nach 7 Tagen ab: Die Dateien werden recycelt, und die alte Adresse liefert dann 404.

• Verschieben Sie die Dateien innerhalb dieser 7 Tage in Ihren eigenen Speicher; behandeln Sie die Adresse nicht als langlebigen Link.
• Eine abgelaufene Adresse erfordert keine neue Generierung und wird nicht erneut berechnet: Rufen Sie diesen Endpunkt (POST /api/music/query) erneut auf, um eine frische gültige Adresse für diesen Song zu erhalten.

2. Song-Verlauf des Kontos abfragen

Listet die Songs des Hauptkontos, zu dem der aktuelle API-Schlüssel gehört. Geeignet für eine eigene Songliste, einen Auswähler oder eine Verlaufsseite.

Endpunkt: GET /api/music/songs

Abrechnung: Kostenlos.

Query-Parameter

Die Ergebnisse sind absteigend nach created_at und interner Datensatz-ID sortiert, damit die Blätterreihenfolge stabil bleibt.

Eine abgelaufene Übermittlung wiederfinden: Generierungs-Endpunkte liefern vor der Annahme keine Zwischenantwort. Wenn Ihr Client beim Senden in einen Timeout lief oder die Verbindung abbrach, kann diese Bestellung bereits angenommen sein und generiert werden. Werfen Sie einen Blick auf diesen Endpunkt (neueste zuerst): Angenommene Songs erscheinen normal in der Liste. Senden Sie erst erneut, wenn Sie sicher bestätigt haben, dass nichts vorliegt — sonst zahlen Sie doppelt. Siehe „Wartezeiten und Timeout-Einstellungen“ in der Übersicht der neuen API.

Beispielanfrage

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Beispielantwort

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "Stadt bei Nacht",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

Antwortfelder

Der Listen-Endpunkt liefert keine Prompts, Abrechnungsfelder, Kontoinformationen oder Rohantworten. Für Prompts und Generierungsparameter rufen Sie den Detail-Endpunkt des Songs auf.

3. Generierungsparameter abfragen

Fragt den Prompt, den Stil, das Modell und den Quellsong ab, die die Plattform bei der Generierung gespeichert hat.

Endpunkt: GET /api/music/songs/:song_id

Abrechnung: Kostenlos.

Es können nur Songs des Hauptkontos gelesen werden, zu dem der aktuelle API-Schlüssel gehört. Songs anderer Nutzer oder von Subsite-Konten werden einheitlich als „Song nicht gefunden“ behandelt.

Pfadparameter

Beispielanfrage

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Beispielantwort

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "Stadt bei Nacht",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "Stadtstraßen nach dem Regen, Songtext über ein Wiedersehen",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "Stadt bei Nacht",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

Die Felder von parameters

Das Feld prompt_view (Prompt ansehen, hinzugefügt am 2026-09-28)

prompt_view ist eine normalisierte Struktur speziell für „Prompt ansehen“: Sie ordnet die Daten je Generierungstyp in feste Abschnitte, sodass der Client nicht mehr entscheiden muss, welches Feld er anzeigt. Es ist ein rein additives Feld — die alten Felder (parameters, parameter_retention) behalten Namen und Bedeutung, und Clients, die das neue Feld nicht auswerten, sind davon völlig unberührt.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Benutzerdefinierter Modus",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Vier Uhr morgens#701f37", "title_base": "Vier Uhr morgens", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "Guochao-Elektronik, tiefer Sub-Bass, Retro-Synth",
    "style_tags": "Guochao-Elektronik, tiefer Sub-Bass, Retro-Synth",
    "style_source": "user", "lyrics": "...",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

Felder, die in extended auftreten können: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, sowie die Soundeffekt-Gruppe sound_type / sound_bpm / sound_key / sound_loop. Leere Werte werden nie zurückgegeben.

Drei Anzeigeregeln (befolgen statt selbst zu schließen):

1. Herkunft des Stils unterscheiden: bei style_source=suno_derived als „Stil (von Suno aus Ihrer Beschreibung abgeleitet)“ anzeigen, niemals als „Ihr Stil“;
2. Interne Prompts erscheinen nie: Stimmen-Cover-Typen geben nur die vom Nutzer eingegebenen 【Stilanforderungen】/【Coveranforderungen】 zurück; das feste Gerüst, das wir für das Modell zusammensetzen, erscheint in keinem Feld (historische Daten sind ebenso bereinigt);
3. Fehlende Parameter nicht erraten: steht etwas nicht in extended, wurde es damals nicht erfasst — erklären Sie das mit retention.

Hinweise zur Parameterspeicherung

parameter_retention trennt „es wurde ausdrücklich ein leerer Wert übergeben“ von „das Feld wurde historisch nie gespeichert“:

• core_parameters_available: ob der Hauptdatensatz der Aufgabe existiert; bei einer gültigen Detailabfrage normalerweise true;
• extended_parameters_available: ob ein zugehöriger erweiterter Musik-Aufgabendatensatz gefunden wurde;
• sources: aus welchen Datentabellen diese Antwort stammt;
• unavailable_fields: Felder, die aus historischen Daten nicht zuverlässig rekonstruierbar sind; sie liefern null in parameters.

Gewöhnliche historische Songs speicherten meist Prompt, Stil, aktuellen Titel, Modell, Generierungstyp und Quellsong, aber nicht alle erweiterten Parameter separat. Die Plattform errät fehlende Werte nie aus dem generation_type.

Einige erweiterte Musik-Aufgaben speicherten zusätzlich den ursprünglichen Prompt, Stil, Titel, Modell sowie custom_mode, negative_tags, vocal_gender, style_weight und weirdness_constraint. Selbst wenn ein erweiterter Datensatz existiert, können instrumental, lyrics_mode und wait_audio weiterhin nicht rekonstruierbar sein.

Titel können später vom Nutzer umbenannt werden. Wenn eine gewöhnliche historische Aufgabe keinen separaten Originaltitel gespeichert hat, kann parameters.title der aktuelle Titel sein; existiert ein erweiterter Aufgabendatensatz, wird der dort gespeicherte ursprüngliche Generierungstitel bevorzugt.

Nicht gefunden oder keine Berechtigung

Geschäftsfehler nutzen einen einheitlichen Antwortumschlag. Wenn der Song nicht existiert oder nicht zum aktuellen Konto gehört:

{
  "success": false,
  "message": "song not found"
}

Dieser Geschäftsfehler wird derzeit mit HTTP 200 zurückgegeben; beurteilen Sie das Ergebnis also am Feld success. Ein fehlender, ungültiger, abgelaufener oder deaktivierter API-Schlüssel liefert HTTP 401.

Sicherheitshinweise

Die Verlaufs- und Detail-Endpunkte geben niemals zurück:

• API-Schlüssel oder Token-IDs;
• Kontingent-, Abrechnungs- oder Erstattungsfelder;
• Kontoinformationen oder Rohantworten;
• interne Schlüssel des Objektspeichers;
• Administrator- oder interne Ressourcenfehler.