API für verstärkten Upload

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

Beschreibung des Endpunkts

Der verstärkte Upload übergibt eine lokale Audiodatei; das System führt die Verstärkung im Hintergrund aus und erzeugt einen vollständigen, abspielbaren Song. Der Aufruf liefert sofort die Aufgabeninformationen zurück, und der Client fragt den Fortschritt über den Abfrage-Endpunkt ab.

Upload-Endpunkt: POST /api/music/enhanced-upload

Abfrage einer Aufgabe: GET /api/music/enhanced-upload/:id

Aufgabe abbrechen: POST /api/music/enhanced-upload/:id/cancel

Listenabfrage: GET /api/music/enhanced-upload

Abrechnung: 10 ¥ pro Aufruf, vorab zum Festpreis von suno-enhanced-upload berechnet. Schlägt die Aufgabe fehl oder wird sie in der zulässigen Phase abgebrochen, wird der vorab berechnete Betrag automatisch erstattet. Der tatsächlich berechnete Betrag folgt der aktuellen Preis-Konfiguration im Backoffice.

Aufrufablauf

1. Rufen Sie POST /api/music/enhanced-upload auf, um die Audiodatei hochzuladen.
2. Speichern Sie die zurückgegebene task_id.
3. Rufen Sie GET /api/music/enhanced-upload/:id auf, um Fortschritt und Ergebnis abzufragen.
4. Nachdem Suno das finale Rendering abgeschlossen hat, ruft der Dienst mit dem an diese Aufgabe gebundenen Suno-Konto den autorisierten Download-Endpunkt von Studio auf und schreibt die MP3 in den CN2-Mediendienst.
5. Erst wenn das CN2-Asset bereit ist, wird die Aufgabe completed; dann lesen Sie die CDN-Audioadresse aus audio_url in der Antwort.

/api/forbidden ist eine Platzhalteradresse, die in den Metadaten von Suno Studio auftauchen kann; sie ist keine abspielbare oder herunterladbare Ressource. Sie wird nie an Kunden zurückgegeben und nicht als Nachweis für den Abschluss verwendet. Ist das Rendering fertig, aber CN2 bereitet noch vor, gibt der Endpunkt weiterhin processing zurück und liefert kein audio_url; der Client sollte weiter abfragen und die leere Adresse nicht als Fehler betrachten.

Verstärkten Upload senden

Headers

Formularparameter

Beispielanfrage

Das folgende Beispiel nutzt dieselbe Aufrufart wie bei der Produktionsvalidierung, der API-Schlüssel wurde jedoch durch einen Platzhalter ersetzt.

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

Antwort

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

Eine Aufgabe abfragen

Beispielanfrage

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

Beispielantwort während der Verarbeitung

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

Beispielantwort nach Abschluss

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

Eine Aufgabe abbrechen

Ein Abbruch ist nur möglich, solange Aufgabe und Backend-Workflow noch in der Phase queued sind. Sobald die Aufgabe leasing, running oder processing erreicht oder abgeschlossen ist, ist ein Abbruch nicht mehr möglich.

Beispielanfrage

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

Antwort

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

Hat die Aufgabe bereits mit der Verarbeitung begonnen, gibt der Endpunkt Folgendes zurück:

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

Aufgabenliste abfragen

Der Listen-Endpunkt gibt nur die verstärkten Uploads des Nutzers zurück, dem der aktuelle API-Schlüssel gehört; gewöhnliche Generierungs-, Cover- und Erweiterungsaufgaben werden nicht beigemischt.

Query-Parameter

Beispielanfrage

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

Antwort

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

Referenz der Antwortfelder

Hinweise

• Dieser Endpunkt unterstützt derzeit nur Multipart-Dateiuploads; JSON file_url und file_base64 werden nicht unterstützt.
• Die hochgeladene Datei darf höchstens 80 MB groß sein.
• Der Upload-Endpunkt ist asynchron: Eine Antwort queued bedeutet, dass die Aufgabe eingereiht wurde, nicht dass das Audio fertig ist.
• Ein Abbruch gilt nur für Aufgaben, die noch nicht mit der Verarbeitung begonnen haben; nach Beginn der Verarbeitung wird der Workflow des Plattformkontos nicht unterbrochen.
• Geben Sie keine echten API-Schlüssel im Client-Code preis.

Nach dem verstärkten Upload ein Cover starten

Nach Abschluss des verstärkten Uploads können Sie das Ergebnis als Quell-Clip verwenden und POST /api/music/generate-from-source aufrufen, um ein Cover zu starten.

Hinweis: Das Cover ist ein synchroner Endpunkt — die Bestellung wird erst mit dem Eintreffen der Antwort angenommen, und gemessene Fälle können bis zu etwa 230 Sekunden dauern. Setzen Sie den Client-Timeout auf 300 Sekunden oder mehr und wiederholen Sie nach einem Timeout nicht sofort. Siehe „Wartezeiten und Timeout-Einstellungen“ in der Übersicht der neuen API.

Fragen Sie zuerst GET /api/music/enhanced-upload/:id ab, bis task.status completed ist. Dann gilt:

• task.song_id ist die echte Song-ID und die vom Cover-Endpunkt benötigte sourceClipId;
• es empfiehlt sich, task.audio_url als sourceAudioUrl mitzugeben, damit der Server den Fall behandeln kann, dass Quell-Clip und ausführendes Konto nicht übereinstimmen;
• task.task_id ist nur die ID der verstärkten Upload-Aufgabe und kann nicht als sourceClipId verwendet werden;
• pending:enhanced-upload:* ist eine Platzhalter-ID der Verarbeitungsphase und kann nicht für ein Cover verwendet werden.

Verwenden Sie beim Starten des Covers denselben API-Schlüssel wie beim verstärkten Upload und bauen Sie die Anfrage nach der folgenden Feldzuordnung auf:

Die übrigen Parameter (Text, Stil, Titel, Modell) füllen Sie gemäß der Cover-aus-Quell-Clip-API aus. Sobald der Cover-Endpunkt die neue clips[].song_id zurückgibt, fragen Sie mit POST /api/music/query den Generierungsstatus und das endgültige Audio ab.