API für Voice-Cloning und Generierung mit Stimme (nicht empfohlen)

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

⛔ Alte Kette, für neue Integrationen nicht empfohlen. Diese Seite beschreibt die frühe persona-Kette (voice_task_id / generate-with-voice). Sie funktioniert weiterhin, wird Kunden gegenüber aber nicht mehr empfohlen; die Navigation links kennzeichnet sie als „nicht empfohlen".

Für neue Integrationen nutzen Sie die 【Empfohlen】 API für Stimmprofile: Erstellen Sie aus einer Stimmprobe ein Stimmprofil (POST /api/music/voice-profile/create) und verwenden Sie es, um einen bestimmten Song zu covern oder einen neuen Song singen zu lassen. Ein Stimmprofil ist eine erstklassige Ressource: es lässt sich auflisten, abrufen und löschen, und das Quellaudio bleibt dauerhaft erhalten.

Wenn Ihr Produkt den vollständigen Kreislauf „Stimme anlegen → langfristig wiederverwenden → Songs covern" braucht, bevorzugen Sie die neue Kette.

Wichtiger Hinweis: Eine geklonte Stimme kann ablaufen.

Die durch Voice-Cloning erzeugte voice_id / voice_task_id ist keine dauerhaft nutzbare Ressource — sie kann wegen ihrer Gültigkeitsdauer, des Kontostatus oder einer Änderung des Stimmenstatus aufhören zu funktionieren. Integratoren dürfen nicht einmal klonen und danach für immer eine lokal zwischengespeicherte Stimm-ID wiederverwenden.

Empfohlenes Vorgehen:

• Speichern Sie voice_task_id, voice_id, is_available, updated_at und den Zeitpunkt der letzten erfolgreichen Generierung.
• Rufen Sie vor jeder Generierung mit einer geklonten Stimme GET /api/voice/clone/tasks/{voice_task_id} oder POST /api/voice/clone/tasks/{voice_task_id}/check auf und bestätigen Sie is_available=true.
• Wenn der Endpunkt meldet, dass die Stimme nicht verfügbar ist, dass die Aufgabe nicht existiert oder selected voice is not ready zurückgibt, bitten Sie den Nutzer, erneut zu klonen oder eine andere verfügbare Stimme zu wählen.
• Versprechen Sie Endnutzern nicht, eine geklonte Stimme sei ein „dauerhaftes Asset"; weisen Sie in der Produktoberfläche darauf hin, dass „eine Stimme ablaufen kann und eine erneute Validierung oder ein erneutes Klonen nötig sein kann".

Beschreibung des Endpunkts

Diese Endpunktgruppe erstellt eine wiederverwendbare Stimme und generiert damit Songs. Aufrufende brauchen nur den von der Plattform ausgestellten API-Key; der Server übernimmt Aufgabenzustellung, Statusabgleich, Abrechnung und Downloads.

Authentifizierung: Authorization: Bearer YOUR_API_KEY

Abrechnung:

• Stimmvalidierung, Voice-Cloning, Statusabfrage, Löschen und Downloads: kostenlos.
• Der Ein-Schritt-Klon-Einstieg im Arbeitsbereich: pauschal 5 ¥ pro Aufruf; er erledigt die Validierung der Quellstimme und das zweite Verifizierungs-Audio automatisch und erstattet bei Fehlschlag.
• Nach einem normalen Klon automatisch mit dem Verifizierungs-Audio fortfahren: pauschal 5 ¥ pro Aufruf; bei Fehlschlag wird nach dem bestehenden Ablauf erstattet.
• Einen Song mit einer geklonten Stimme generieren: kostenpflichtig, pauschal 1,2 ¥ pro Aufruf; jeder Aufruf liefert üblicherweise 2 Platzhalteraufgaben.
• Mit aktiviertem Max Mode (max_mode: true bei POST /api/music/generate-with-voice) werden die 1,2 ¥ pro Aufruf mit dem 2-fachen berechnet, also 2,4 ¥ pro Aufruf; die Stimmgenerierung unterstützt außerdem variety (0-4, ohne Zusatzkosten) — die Regeln stehen im Abschnitt „Erweiterte Parameter" der Übersicht der neuen API.

Ablauf der Aufrufe

1. Rufen Sie POST /api/voice/clone/validate auf, um die Quellstimme hochzuladen und eine voice_task_id zu erhalten.
2. Warten Sie auf GET /api/voice/clone/tasks/{voice_task_id} oder fragen Sie die Aufgabe ab, bis Sie validate_info erhalten.
3. Der Nutzer liest diesen Text vor und nimmt das Verifizierungs-Audio auf.
4. Rufen Sie POST /api/voice/clone/tasks/{voice_task_id}/generate auf, um das Verifizierungs-Audio einzureichen.
5. Rufen Sie POST /api/voice/clone/tasks/{voice_task_id}/check auf oder fragen Sie die Aufgabe weiter ab, bis is_available=true gilt.
6. Rufen Sie POST /api/music/generate-with-voice auf, um mit dieser Stimme einen Song zu generieren.
7. Der Generierungs-Endpunkt liefert zunächst Platzhalteraufgaben; sobald die Generierung fertig ist und Sie die echte song_id haben, können Sie über die Download-Endpunkte eine einzelne Datei oder ein Paket holen.
8. (Optional) Wenn die Stimme nicht mehr gebraucht wird, rufen Sie DELETE /api/voice/clone/voices/{voice_task_id} auf, um sie zu löschen — die Semantik steht in Abschnitt 6.

Es gibt außerdem das Ein-Schritt-Klonen: Auf der ersten Aufnahme-/Upload-Seite im Arbeitsbereich können Sie den Abschluss in einem Schritt wählen; das System erledigt Validierung und Stimmerstellung zusammen, sodass Sie kein zweites Verifizierungs-Audio aufnehmen müssen; es kostet 5 ¥ pro Aufruf und wird bei Fehlschlag erstattet.

Felder der Stimmaufgabe

1. Quellstimme zur Validierung einreichen

Endpunkt: POST /api/voice/clone/validate

Body-Parameter

vocal_end_s - vocal_start_s muss die Mindestanforderung an das Gesangssegment erfüllen. Laden Sie eine klare Gesangsaufnahme ohne deutliche Begleitung oder Störgeräusche hoch.

Beispielanfrage

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "Meine chinesische Frauenstimme",
    "description": "Klare, natürliche chinesische Frauenstimme",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Beispielantwort

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Meine chinesische Frauenstimme",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Stimmaufgabe abfragen

Endpunkt: GET /api/voice/clone/tasks/{voice_task_id}

Beispielanfrage

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Beispielantwort

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Meine chinesische Frauenstimme",
      "validate_info": "Bitte lesen Sie den hier zurückgegebenen Verifizierungstext vor",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Verifizierungstext neu erzeugen

Endpunkt: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Aufrufen, wenn der Verifizierungstext zum Vorlesen ungeeignet ist oder die Validierung wiederholt werden muss.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Verifizierungs-Audio einreichen und Stimme erstellen

Endpunkt: POST /api/voice/clone/tasks/{voice_task_id}/generate

Body-Parameter

Beispielanfrage

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "Meine chinesische Frauenstimme"
  }'

5. Prüfen, ob die Stimme nutzbar ist

Endpunkt: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Wenn die Aufgabe nutzbar ist, steht is_available in der Antwort auf true und es wird eine voice_id zurückgegeben.

6. Stimme löschen

Endpunkt: DELETE /api/voice/clone/voices/{voice_task_id}

Abrechnung: kostenlos.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Beispielantwort

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

Was nach dem Löschen passiert

• Die Stimme kann keine neuen Songs mehr generieren: Ein Aufruf von POST /api/music/generate-with-voice mit dieser voice_task_id (oder ihrer voice_id) wird mit der Meldung selected voice is not ready abgelehnt, ohne Berechnung.
• Bereits damit generierte Songs bleiben völlig unberührt: Wiedergabe, Download, Fortsetzen, Ersetzen und Stem-Trennung funktionieren wie zuvor.
• Diese Stimmaufgabe verschwindet aus Abfragen: GET /api/voice/clone/tasks/{voice_task_id} gibt record not found zurück.
• Das Quellaudio bleibt gemäß der dauerhaften Aufbewahrungsrichtlinie der Plattform erhalten (seit 2026-09-23 wird beim Löschen die hochgeladene Stimmprobe nicht mehr bereinigt), aber das bedeutet nicht, dass es wiederhergestellt werden kann: Diese alte Aufgabe ist beendet, und um dieselbe Stimme weiter zu nutzen, muss der Klon-Ablauf erneut durchlaufen werden, was eine neue voice_task_id ergibt.
• Doppeltes Löschen: Wird dieselbe Aufgabe erneut gelöscht, kommt record not found zurück (sie ist bereits im gelöschten Zustand und nicht mehr auffindbar).

7. Einen Song mit einer geklonten Stimme generieren

Endpunkt: POST /api/music/generate-with-voice

Abrechnung: 1,2 ¥ pro Aufruf.

Body-Parameter

suno-v6, suno-v6-wild und suno-v6-mini werden unterstützt; ein leeres Modell wird als suno-v6 behandelt. Die alten Modelle V5/V5.5 sind eingestellt, doch historische Aufgaben können weiterhin die alten Modellnamen zeigen.

Die gemeinsame Anfragestruktur verarbeitet auch Create-UI-Kompatibilitätsfelder wie task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId und voiceId, doch sind sie keine gültigen Kundenparameter für diesen Endpunkt: Eine Stimmaufgabe muss als voice_task_id gesendet werden, eine optionale Stimmprüfung als voice_id, und die Musikgenerierung mit Stimme liest die sound-Felder nie.

Hinweise zum Ausfüllen der Generierungsparameter

• Bei customMode=false enthält prompt die Songbeschreibung; bei customMode=true enthält prompt den vollständigen Songtext, und style und title müssen ebenfalls gefüllt sein. Senden Sie Songtexte nicht in das Beschreibungsfeld des Inspirationsmodus und behandeln Sie eine Songbeschreibung nicht als Songtext des erweiterten Modus.
• weirdnessConstraint und styleWeight sind Dezimalverhältnisse von 0.0 bis 1.0; 50 oder 50% sind nicht zulässig. 0.5 ist ein ausgewogener Wert; Weglassen bedeutet „nicht angegeben", und 0 ist ein gültiger expliziter Wert.
• vocalGender akzeptiert nur m, male, f oder female. instrumental ist hier nur ein Kompatibilitätsfeld — die Generierung mit geklonter Stimme wird immer als Gesangssong behandelt.
• waitAudio ändert hier nichts; der Endpunkt liefert immer asynchron Platzhalteraufgaben. Ein leeres audio_url im ersten Ergebnis ist normal: Fragen Sie mit client_request_id ab und lesen Sie die Audioadresse erst, wenn das Ergebnis fertig ist.

Header-Parameter

Verhalten von Idempotency-Key:

• Die erste Anfrage schreibt vor der Abrechnung einen dauerhaften Idempotenz-Datensatz;
• Ist derselbe Schlüssel mit derselben Anfrage bereits abgeschlossen, wird die erste Annahmeantwort wiederholt, ohne zweite Abrechnung und ohne zweite Aufgabe;
• Derselbe Schlüssel mit anderem Anfragetext wird abgelehnt;
• Derselbe Schlüssel, der noch verarbeitet wird, liefert einen stabilen „in Verarbeitung"-Fehler und gibt eine sichere client_request_id erst zurück, wenn eine erzeugt wurde;
• Schlägt die erste Anfrage unter einem Schlüssel fehl, bleibt der Fehlstatus bestehen; ein erneuter Versuch erfordert einen neuen Schlüssel.

Bedingungen für das Covern mit sourceClipId

Das Covern aus einer Quelle über die Kunden-API wird vollständig serverseitig behandelt: Der Zugriff auf den Quellsong wird serverseitig gelöst und der Kunde übermittelt keine Kontodaten. Ob es möglich ist, entscheidet die tatsächliche Antwort des Endpunkts.

Die Quelle muss dem aktuellen API-Nutzer gehören, ein abgeschlossener Workspace-Song sein, der nicht pending: ist, und nutzbares Audio haben. Unterstützt werden normale Generierung, Quellen aus normalem Upload und der Endsong eines verstärkten Uploads; Zwischenstände des verstärkten Uploads werden vor der Abrechnung abgelehnt. Der Server akzeptiert nur die vom Kunden gesendete Quellsong-ID und niemals eine Konto-ID; eine nicht verfügbare oder nicht abgeschlossene Quelle führt vor der Abrechnung zu einem Fehler.

Beispielanfrage

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "Schreibe einen chinesischen Popsong über einen Strand in einer Sommernacht",
    "style": "Mandopop, warm piano, emotional",
    "title": "Meeresbrise in einer Sommernacht",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Beispielantwort

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Meeresbrise in einer Sommernacht",
        "prompt": "Schreibe einen chinesischen Popsong über einen Strand in einer Sommernacht"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Meeresbrise in einer Sommernacht",
        "prompt": "Schreibe einen chinesischen Popsong über einen Strand in einer Sommernacht"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Zu Platzhalteraufgaben und der endgültigen song_id

generate-with-voice ist ein asynchroner Generierungs-Endpunkt. Eine erfolgreiche Antwort bedeutet nur, dass die Generierungsaufgabe eingereicht wurde, nicht dass der Song fertig ist.

Bedeutung der wichtigen Antwortfelder:

Achtung: Eine placeholder_id, die mit pending: beginnt, kann nicht als endgültige song_id verwendet werden und auch nicht an /api/music/query oder die Download-Endpunkte übergeben werden. Ein Aufruf von /api/music/query nur mit pending:*-Werten kann ein leeres Array [] liefern, weil der echte Song noch nicht fertig ist oder die Platzhalteraufgabe noch nicht durch die endgültige Song-ID ersetzt wurde.

Falsches Beispiel:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

Richtiger Ablauf:

1. Rufen Sie POST /api/music/generate-with-voice auf, um die Stimmgenerierungsaufgabe einzureichen.
2. Speichern Sie client_request_id, items[].placeholder_id und items[].client_request_index aus der Antwort.
3. Fragen Sie GET /api/music/generate-with-voice/results?client_request_id=cu_xxx in einer Schleife ab.
4. Sobald items[].song_id einen Wert hat, der nicht mit pending: beginnt, rufen Sie /api/music/query, /api/music/download-file oder /api/music/download-all auf.

Die aktuelle Version ergänzt einen öffentlichen Abfrage-Endpunkt:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

Er gibt die Aufgabenergebnisse zu derselben client_request_id für den aktuellen Nutzer zurück, sodass Kunden die endgültige song_id selbst nachschlagen können. In der zurückgegebenen Liste:

• song_id ist die echte Song-ID;
• placeholder_id erscheint nur, solange die Aufgabe noch im Platzhalterzustand ist;
• ein Wert, der mit pending: beginnt, kann nicht mit /api/music/query oder den Download-Endpunkten verwendet werden.

Wenn Sie nur die client_request_id oder eine pending:*-Platzhalter-ID gespeichert haben, rufen Sie zuerst diesen Ergebnis-Endpunkt auf; ist die echte song_id weiterhin nicht zu finden, senden Sie die client_request_id an den technischen Support zur Lokalisierung.

Ergebnisse der Stimmgenerierung abfragen

Endpunkt: GET /api/music/generate-with-voice/results

Abrechnung: kostenlos.

Query-Parameter

Beispielanfrage

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Beispielantwort während der Verarbeitung

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "Meeresbrise in einer Sommernacht"
      }
    ]
  }
}

Beispielantwort nach Abschluss

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "Meeresbrise in einer Sommernacht",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Bedeutung des obersten status

8. Eine einzelne Datei herunterladen

Endpunkt: POST /api/music/download-file

Body-Parameter

Beispielanfrage

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

Die Antwort ist ein Dateistream; Content-Type und Dateiname folgen dem, was das Backend zurückgibt.

9. Song-Ressourcen als Paket herunterladen

Endpunkt: POST /api/music/download-all

Body-Parameter

Beispielanfrage

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

Das Paket enthält üblicherweise das Audio, das Cover und metadata.json; ist eine Ressourcenart noch nicht erzeugt, wird sie nicht ins Archiv aufgenommen.

Häufige Fehler

Fehler dieser Endpunktgruppe liefern immer HTTP 200: Beurteilen Sie den Erfolg am Feld success im Antworttext (false bedeutet Fehlschlag, der Grund steht in message) und schauen Sie nicht nur auf den HTTP-Statuscode. Die vollständige Semantik des Löschens einer Stimme (ob sie weiter nutzbar ist, ob sie wiederhergestellt werden kann) steht in Abschnitt 6.