【Empfohlen】 API für Stimmprofile

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

✅ Für neue Integrationen empfehlen wir diese Kette. Nach den realen Bewertungen vieler Nutzer behalten Songs aus dieser Kette die Originalstimme sehr gut: Die Stimme in der fertigen Spur klingt näher an der Person aus der hochgeladenen Probe. Deshalb ist dies der Weg, den wir Kunden derzeit empfehlen.

Zum Vergleich: Die frühere API für Voice-Cloning und Generierung mit Stimme funktioniert weiterhin, ist in der Navigation aber als „nicht empfohlen" gekennzeichnet und wird für neue Integrationen nicht mehr empfohlen.

• Dokumentdatum: 2026-09-26
• Abgedeckte Fähigkeiten: eigene Stimme anlegen → damit einen bestimmten Song covern / einen neuen Song singen → Fortschritt abfragen → Ergebnisse herunterladen
• Alle Endpunkte, Felder und Antworten wurden mit echten Aufrufen geprüft (mit „gemessen" markierte Punkte wurden im Detail verifiziert)

Hinweis: Dieses Dokument beschreibt nur die Endpunkte, die Sie aufrufen. Medienverarbeitung, Aufgabenplanung und Inhaltsprüfung erledigt der Server automatisch; der Client implementiert sie nicht.

0. In fünf Minuten startklar

Vier Schritte genügen, um aus einer Stimmprobe zwei fertige Songs zu machen.

① Stimme anlegen  POST /api/music/voice-profile/create      → voice_id erhalten (status=ready)
② Damit covern    POST /api/music/voice-profile/cover       → sofort 2 song_id erhalten
③ Fortschritt     POST /api/music/query                     → bis status=completed abfragen
④ Herunterladen   GET  /api/music/download?song_id=…&kind=mp3

Minimales Arbeitsbeispiel (curl):

API_KEY="sk-Ihr-Schluessel"
BASE="https://www.suno-api.io"

# ① Stimme anlegen (Stimmprobe hochladen; 10 s oder mehr, unter 10 MB empfohlen)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=Meine Stimme" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② Mit dieser Stimme einen Song covern (song_clip_id = die clip id des Songs)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\nSongtext…",
        "style_requirements": "langsamer Folk, Akustikgitarre",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ Abfragen (mehrere ids auf einmal, durch Kommas getrennt)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ Nach Abschluss die mp3 laden (nur bei status=completed gibt es eine Datei)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. Gemeinsame Konventionen

1.1 Domain und Umgebung

Alle Pfade unten sind relativ zur Base URL; die vollständige Adresse von POST /api/music/voice-profile/create lautet zum Beispiel https://www.suno-api.io/api/music/voice-profile/create.

1.2 Authentifizierung

Alle Endpunkte nutzen denselben Anfrage-Header, dessen Wert der in der Konsole erstellte API-Key ist:

Authorization: Bearer sk-xxxxxxxx

• Das Präfix Bearer ist optional; das Präfix sk- ebenfalls (Authorization: sk-xxx funktioniert genauso).
• Key fehlt oder ist ungültig → HTTP 401, mit einem Body wie {"success":false,"message":"…"} (der Text richtet sich nach der Ansprachesprache).
• Jeder Key sieht und bearbeitet nur die Songs und Stimmen des eigenen Kontos.

1.3 Formate des Anfrage-Bodys

• Stimme anlegen: multipart/form-data (Datei hochladen) wird empfohlen; application/json (URL oder base64) wird ebenfalls unterstützt.
• Alle anderen Endpunkte: application/json.

1.4 Zwei Antwort-Hüllen (Kunden müssen nur diese beiden kennen)

Die Endpunkte zur „Stimmenverwaltung" (create / create-from-clip / list / detail / delete) nutzen die Fach-Hülle:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

Das „Covern mit Stimme" läuft über den Generierungskanal und nutzt die Generierungs-Hülle: Erfolg ist code/message/data, Fehler ist ein error-Objekt:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

So entscheiden Sie: zuerst den HTTP-Statuscode ansehen, dann success === false, zuletzt code !== 200 oder das Vorhandensein von error. Ein Fachfehler garantiert keinen von 200 abweichenden HTTP-Status (die Endpunkte zur Stimmenverwaltung liefern bei Fehlern weiterhin HTTP 200), Sie dürfen sich also nicht allein auf den Statuscode verlassen.

1.5 Idempotenz

Das Anlegen einer Stimme (einschließlich „aus vorhandenem Audio anlegen") ist wirklich idempotent: Unter demselben Key legt ein erneut gesendeter gleicher client_request_id nur eine Stimme an, und der zweite Versuch gibt direkt das erste Ergebnis zurück (success=true, dieselbe voice_id). Gedacht ist das so, dass der Client selbst eine id erzeugt (etwa eine UUID) und beim erneuten Versuch nach einem Timeout denselben Wert wiederverwendet.

Das Senden eines Covers dedupliziert nicht auf Anfrageebene (es ist eine kostenpflichtige Generierung), beachten Sie daher zwei Punkte:

1. Die Sende-Kennung steht im Header X-Create-Ui-Client-Request-Id: <Ihre Sende-id>. Sie wird in den serverseitigen Aufgaben-Datensatz geschrieben, um spätere Untersuchungen zu erleichtern; sie verhindert keine doppelte Abbuchung.
2. Ein Timeout ≠ ein Fehlschlag: Die Anfrage kann bereits angenommen worden und in Generierung sein. Prüfen Sie vor einem erneuten Versuch mit GET /api/music/songs?p=1&page_size=20 (die Paginierungsparameter sind p / page_size; die kompatible Schreibweise ps funktioniert ebenfalls), ob bereits ein neuer Song mit generation_type=voice_profile_cover aufgetaucht ist, und senden Sie dieselbe Anfrage nur dann erneut, wenn nicht.

Die Bodies von create und create-from-clip nehmen ebenfalls ein Feld client_request_id (siehe §3 und §4).

1.6 Abrechnungsüberblick

Die Preise lassen sich jederzeit über einen öffentlichen Endpunkt lesen, also nicht fest verdrahten (siehe §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← Grundpreis für ein Cover mit Stimme
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← Preis für den verstärkten Klon
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

Beim Covern gilt Vorabbuchung + Erstattung bei Fehlschlag:

• Eine abgelehnte Anfrage (falsche Parameter, ein 4xx/5xx der Plattform, unzureichendes Guthaben an sich) wird nicht berechnet — beim Senden mit einer nicht existierenden Stimme blieb das Guthaben in unseren Messungen völlig unverändert (delta = 0);
• Eine angenommene Aufgabe, die letztlich scheitert (einschließlich eines Dienstfehlers der Plattform), läuft über den Erstattungsweg des Servers und gibt den vorab gebuchten Betrag zurück.

1.7 Status-Übersicht

Der status der Stimme:

Der status des Songs (der von den Abfrage-Endpunkten zurückgegebene Wert):

2. Endpunkt-Überblick

3. Eine Stimme anlegen

POST /api/music/voice-profile/create

Registrieren Sie ein Stück Gesangs-Audio als „Stimme" und erhalten Sie eine voice_id. Für die Plattform ist eine Stimme schlicht „ein Audio + sein Clip im Katalog", daher bleibt dieses Quellaudio nach erfolgreichem Anlegen dauerhaft erhalten (für spätere Cover).

3.1 Drei Eingabeformen (wählen Sie eine)

Form A: Multipart-Datei-Upload (empfohlen)

Content-Type: multipart/form-data

file=<Audio-Binärdaten>      # erforderlich
title=<Stimmenname>          # optional; wenn leer, der Dateiname ohne Endung
file_name=<ursprünglicher Dateiname>
source_file_name=<ursprünglicher Dateiname>
source_kind=upload|record    # optional, Herkunftsmarke (Upload / Aufnahme); Standard upload
enhanced=false|true          # optional, true = verstärkter Klon (siehe §3.5)
client_request_id=<Idempotenzschlüssel>   # optional
voice_id=<eigene ID>         # optional, selten genutzt

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=Meine Stimme" \
  -F "source_kind=upload"

Form B: JSON + eine öffentliche Audio-URL

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "Meine Stimme"
      }'

• Die URL muss ein öffentlich erreichbarer HTTPS-Direktlink sein; der Server lädt sie einmal herunter und legt sie in unserem Objektspeicher ab.
• Sie können die Adresse auch in das Feld audio_url schreiben, der Effekt ist gleich (werden beide gesendet, gewinnt file_url).
• Liegt die Adresse bereits auf dem Objektspeicher dieser Plattform (*.myqcloud.com/create-ui/voice-source/...), wird nichts erneut geladen: sie wird direkt registriert.

Form C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "Meine Stimme"
}

• Sowohl das Präfix data:audio/xxx;base64, als auch reines base64 werden akzeptiert.
• Die Größe ist begrenzt (base64 bläht um 1,33× auf), für große Dateien nutzen Sie daher Form A.

3.2 Anforderungen an das Audio

3.3 Antwort

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "Meine Stimme",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

Felder-Referenz (create / list / detail teilen denselben Feldsatz):

created_at / updated_at sind Zeitstempel in Sekunden (10 Ziffern), nicht in Millisekunden.

3.4 Häufige Fehler

3.5 Verstärkter Klon (enhanced=true)

Für Fälle, in denen „die Stimmprobe selbst geschützte Songtexte enthält / ein verstärkter Upload nötig ist". Abgerechnet zum Preis für verstärkten Upload (standardmäßig 10 ¥ pro Aufruf, bei Fehlschlag automatisch erstattet):

• Die Antwort ist sofort status=processing + task_id (noch keine clip_id) und läuft asynchron;
• Während der Verarbeitung fragen Sie mit GET /api/music/voice-profile/{voice_id} den Fortschritt ab; geliefert werden progress_percent / progress_stage / progress_message;
• Bei Abschluss wird status zu ready und clip_id, audio_url, image_url werden ergänzt;
• Bei Fehlschlag wird status=failed und error_message lautet etwa „der verstärkte Upload ist fehlgeschlagen; der Betrag wurde automatisch erstattet, bitte später erneut versuchen";
• Ein verstärkter Klon dauert deutlich länger als ein Standard-Anlegen (Minuten), warten Sie also nicht mit einer synchronen Timeout-Logik.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=Meine Stimme" -F "enhanced=true"

4. Eine Stimme aus vorhandenem Audio anlegen

Wenn Sie nicht erneut hochladen möchten: Kopieren Sie ein Audio, das Sie bereits hochgeladen oder erzeugt haben, direkt in eine Stimme. Kostenlos und idempotent.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: die clip id eines abgeschlossenen Audios in Ihrem Konto (entspricht der song_id des Songs).
• Wird derselbe Clip erneut gesendet, entsteht kein neuer Datensatz: die vorhandene Stimme kommt direkt mit reused: true zurück (gemessen).

Die Antwort umfasst alle Felder aus §3.3 plus zwei schreibgeschützte Felder:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

Fehler (der message wie zurückgegeben; direktes Anzeigen oder Lokalisieren wird empfohlen):

5. Stimmenliste / Details / Löschen

5.1 Liste

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "Meine Stimme", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

Die Felder entsprechen genau §3.3. Gelöschte Stimmen werden standardmäßig nicht zurückgegeben.

5.2 Details

GET /api/music/voice-profile/{voice_id}

Liefert ein einzelnes Stimmenobjekt (data ist das Objekt selbst, kein Array). Läuft ein verstärkter Klon, kommen zusätzlich mit:

5.3 Löschen

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• Nach dem Löschen verschwindet die Stimme aus der Liste und kann nicht mehr für neue Cover genutzt werden: ein Senden mit dieser voice_id liefert 400 (siehe §6.4).
• Bereits damit erzeugte Songs sind völlig unberührt; Wiedergabe, Download, Fortsetzen, Ersetzen und Trennung funktionieren wie zuvor.
• Das Löschen einer nicht existierenden Stimme oder einer, die nicht zu diesem Konto gehört, liefert {"success":false,"message":"voice not found"}.

6. Mit einer Stimme covern (der Kernendpunkt)

POST /api/music/voice-profile/cover
Content-Type: application/json

Ein Senden erzeugt 2 Songs (wie die normale Generierung).

6.1 Zwei Szenarien

Das resolved_scene der Antwort gibt cover oder sing zurück, sodass Sie den gewählten Weg bestätigen können.

6.2 Anfragefelder

Senden Sie zusätzlich den Header X-Create-Ui-Client-Request-Id: <dieselbe Sende-id>: nur dieser wird in den serverseitigen Aufgaben-Datensatz geschrieben und dient als Schlüssel für die spätere Untersuchung (siehe §1.5).

Einheiten beachten: audio_weight / style_weight / weirdness_constraint sind Dezimalzahlen von 0 bis 1, variety ist eine Ganzzahl von 0 bis 4 und duration ist in Sekunden. Verwechslungen führen zu Ablehnungen oder seltsamen Ergebnissen.

Der Songtext ist in Szenario B optional (das Modell erledigt das selbst), aber senden Sie immer lyrics, wenn ein bestimmter Inhalt gesungen werden soll.

6.3 Antwort

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[Aufgabe] Dies ist ein Cover. … (der feste Strukturteil des Servers + Ihre Cover- / Stilvorgaben)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

Kernpunkte:

1. Identifizieren Sie die fertigen Songs über clips[].song_id (dieser Endpunkt liefert kein Feld id).
2. Sie erhalten sofort 2 song_id-Werte, während status noch processing ist (das heißt nur „angenommen") und audio_url leer ist; vor dem Download müssen Sie bis completed abfragen. play_url ist der Vorschau-Stream der Plattform, kann schon beim Senden erscheinen und läuft ab.
3. description ist der Prompt, den der Server letztlich sendet (der feste Strukturteil + Ihre cover_requirements / style_requirements); er ist bei der Ergebnisanalyse sehr nützlich.
4. source_updates ist das Ergebnis der Medienverarbeitung des Servers und kann vom Client ignoriert werden.
5. Die von Ihnen gesendete title wird in den serverseitigen Aufgaben-Datensatz geschrieben und erscheint in späteren Abfragen als song_title; dass clips[].song_title in der Sendeantwort leer ist, ist normal.

6.4 Fehler

{ "error": { "message": "diese Stimme existiert nicht oder wurde gelöscht (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

Unzureichendes Guthaben liefert direkt beim Senden einen Abrechnungsfehler und hinterlässt nie eine halbfertige Aufgabe.

6.5 Verfügbare Modelle (Kundennamen)

Verwenden Sie die Modellnamen für Kunden (die oben). chirp-* sind interne Plattformnamen und sollten nicht direkt verwendet werden.

7. Fortschritt abfragen

7.1 Stapelabfrage (empfohlen)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids ist eine durch Kommas getrennte Zeichenkette (kein Array).
• Die Antwort ist ein nacktes Array (direkt [...], ohne success / data-Hülle):

[
  {
    "song_id": "0f2a…",
    "song_title": "Zwei Tiger",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[Aufgabe] Dies ist ein Cover. … (der endgültige Prompt des Servers)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

Abfrageempfehlung: alle 5–10 Sekunden, mit einem Gesamt-Timeout von 10–15 Minuten (das langsamste gemessene kalte Konto brauchte etwa 4,5 Minuten; sehr wenige brauchen länger). Beurteilen Sie den Abschluss nicht am leeren audio_url, sondern am status.

Kompatibilitätshinweis: Dieser Endpunkt identifiziert Songs über song_id; in einigen frühen Antworten tauchte ein Feld id auf, daher ist row.song_id || row.id die sichere Lesart.

7.2 Details zu einem Song

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "Zwei Tiger",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "Zwei Tiger",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• Hier sind created_at / completed_at Unix-Sekunden (anders als die ISO-Zeichenketten der Stapelabfrage, Clients sollten sie unterscheiden).
• wav_url / video_url sind die Download-Einstiege dieser Plattform (relativ zur aktuellen Domain), ein GET holt die Datei; sie sind leere Zeichenketten, wenn die Plattform dieses Material nicht erzeugt hat.
• parameter_retention sagt, auf welche Sendeparameter dieser Song zurückführbar ist: core_parameters_available=true heißt, dass Kernparameter (Songtext / Stil / Quelle) abfragbar sind, und bei extended_parameters_available=false wurden die oben gelisteten erweiterten Parameter nicht behalten (Cover mit Stimme fallen derzeit in diese Kategorie).

7.3 Meine Werke

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=Stichwort

Paginierungsparameter: p (Seitennummer ab 1) / page_size (Einträge pro Seite; ps ist eine kompatible Schreibweise). Optional status und q (ein Titelstichwort). Standardmäßig absteigend nach Erstellzeit sortiert.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "Zwei Tiger",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

Mit generation_type=voice_profile_cover unterscheiden Sie „Songs aus einem Cover mit Stimme" von anderen Generierungsergebnissen.

8. Die fertigen Songs herunterladen

8.1 Die mp3 direkt holen (empfohlen, kostenlos)

Alle drei gehen; wählen Sie eine:

1. Das audio_url aus dem Abfrageergebnis nutzen (ein Direktlink zum Objektspeicher, am einfachsten).
2. GET /api/music/download?song_id=<id>&kind=mp3 → liefert direkt den Audio-Byte-Stream (der Dateiname steht schon in Content-Disposition).
3. POST /api/music/download-url (um eine signierte temporäre Adresse zu erhalten).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

kind-Werte: mp3 (entspricht song) / playback (Streaming-Wiedergabe) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) ist derzeit nur für manche Songs verfügbar; wenn es fehlschlägt, erzeugen Sie die Datei selbst mit der API für Songtexte mit Zeitstempeln. Die Antwort ist der reine Datei-Byte-Stream, mit bereits gesetztem Content-Type und Content-Disposition (Dateiname); die von GET /api/music/songs/{song_id} gelieferten wav_url / video_url sind derselbe Einstieg mit kind=wav|video.

8.2 In wav umwandeln / Songtext / Metadaten holen (kostenpflichtig)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files akzeptiert: mp3 / wav / lyrics / metadata, bis zu 10 Songs auf einmal.
• Abrechnung pro erfolgreichem Song (0,2 ¥ je): Ein Song, der ganz scheitert, wird nicht berechnet, und ein gescheitertes Format erscheint nur in songs[].errors.
• Um bereits geholte Dateien erneut zu bekommen, nutzen Sie zuerst den kostenlosen POST /api/music/free2/cached (dieselben song_ids + files), um archivierte Adressen zu erhalten; dessen songs[].missing_files listet die Formate, die nicht im Cache liegen und neu vorbereitet werden müssen.

9. Preise abfragen

GET /api/pricing/catalog

Ein öffentlicher Endpunkt ohne Authentifizierung. Alle Einzelpreise, die der Kunde anzeigen muss, stehen in data.catalog.meta (Zeichenketten):

Die Preise werden im Backoffice angepasst, lesen Sie sie also live, statt sie im Client fest zu verdrahten. Die tatsächliche Cover-Buchung = voice_generation_price × (bei wahrem max_mode nochmals max_mode_factor).

10. Grenzen und Hinweise

1. Upload-Größe: ≤ 10 MB (der Server akzeptiert mehr, aber das Eingangs-Gateway schneidet übergroße Bodies bei 10 MiB ab, was als „von Suno abgelehnt" erscheint; blocken Sie es zuerst auf Ihrer Seite).
2. Probendauer: mindestens 6 s, 10–60 s empfohlen; zu kurz und die Plattform lehnt ab.
3. Probeninhalt: sauberer Gesang; vermeiden Sie alles, was einer vorhandenen Aufnahme stark ähnelt (der Katalogvergleich lehnt es ab).
4. Textgrenzen: lyrics ≤ 3000 Zeichen; für style_requirements / negative_tags / title empfehlen sich 1000 / 1000 / 100 Zeichen (Stil- und Cover-Vorgaben werden an den Prompt angehängt, halten Sie die Summe unter 3000 Zeichen).
5. Songtexte werden nicht umgeschrieben: was Sie übergeben, wird gesungen (Zeichen für Zeichen), ohne lokales Kürzen.
6. Jeder Song liefert 2 Spuren; gehen Sie nicht von einem einzelnen Ergebnis aus.
7. Das Quellaudio bleibt dauerhaft erhalten: Das Löschen einer Stimme räumt ihr Quellaudio nicht weg; das hält spätere Cover möglich und die Compliance nachvollziehbar.
8. Die Stimme muss bereit sein: Eine Stimme im Status processing kann nicht zum Covern genutzt werden.
9. Anfrage-Timeout: Bei einem kalten Konto dauerte das erste Senden in unseren Messungen bis zu etwa 4,5 Minuten, setzen Sie den Client-Timeout also auf ≥ 6 Minuten. Cover deduplizieren nicht auf Anfrageebene, prüfen Sie daher nach einem Timeout, ob schon ein neuer Song aufgetaucht ist (§1.5), bevor Sie erneut senden.
10. Eigentum an der Stimme: Stimmen gehören ihrem Ersteller; ein Cover akzeptiert nur bereite und nicht gelöschte Stimmen. Eine nicht existierende, gelöschte oder zu einem anderen Konto gehörende Stimme liefert 400: diese Stimme existiert nicht oder wurde gelöscht (voice_id=…).

11. Häufige Fragen (FAQ)

F1. Kostet das Anlegen einer Stimme Geld? Standard-Anlegen und „aus vorhandenem Audio anlegen" sind kostenlos; berechnet werden nur Cover (1,2 ¥ / MAX 2,4 ¥) und verstärkte Klone (standardmäßig 10 ¥).

F2. Kann ich einen fertigen Song mit Begleitung als Stimmprobe nutzen? Nicht empfehlenswert. Alles mit Musik oder starke Ähnlichkeit mit einer vorhandenen Aufnahme im Katalog lehnt die Plattform ab (This audio matches an existing recording in our catalog.). Nutzen Sie eine rein vokale, trockene Aufnahme.

F3. Warum ist audio_url nach dem Senden eines Covers leer? Das Senden bedeutet nur, dass es angenommen wurde, und status ist noch processing. Eine abspielbare/herunterladbare Adresse erscheint erst, wenn Sie /api/music/query bis status=completed abgefragt haben.

F4. Muss ich in Szenario B (ohne song_clip_id) einen Songtext senden? Optional. Senden Sie lyrics, um einen bestimmten Inhalt zu singen; ohne erledigt das Modell es selbst, aber mit weniger Kontrolle.

F5. Kann vom Kunden hochgeladenes Audio direkt als Stimme dienen? Ja: über die file_url-Form von create, oder indem Sie es zuerst als Song hochladen und dann create-from-clip aufrufen.

F6. Wird bei einem Fehlschlag Geld erstattet? Eine rundheraus abgelehnte Anfrage (falsche Parameter / Plattformfehler) wird nicht berechnet, wie gemessen; eine angenommene, letztlich gescheiterte Aufgabe gibt den vorab gebuchten Betrag zurück. Bei endgültigem Fehlschlag meldet die Aufgabe status=failed plus error_message.

F7. Kann ich nach dem Löschen einer Stimme früher damit erzeugte Songs noch hören? Ja. Das Löschen betrifft nur, ob diese Stimme für neue Cover genutzt werden kann.

F8. Wie lange kann ein Song auf einmal gecovert werden? duration nimmt 1–480 Sekunden; ohne Angabe entscheidet die Plattform anhand des Originalsongs / Materials. Beachten Sie: Die fertigen Spuren der Plattform sind mindestens etwa 30 Sekunden lang; mit einem kleineren Wert kamen in den Messungen weiterhin 29,96 / 29,76 Sekunden heraus.

Anhang A: vollständiges Beispiel (Node.js, mit Abfrage und Download)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① Stimme anlegen (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② Covern
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "langsamer Folk, Akustikgitarre",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ Bis zum Abschluss abfragen (alle 5 Sekunden, höchstens 15 Minuten)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // nacktes Array
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ Herunterladen
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "Meine Stimme");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nSongtext…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

Anhang B: Änderungsprotokoll