API zum Hochladen von Quellaudio

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

Beschreibung des Endpunkts

Das Hochladen von Quellaudio macht aus einer lokalen oder entfernten Audiodatei einen Quell-Clip, den spätere Funktionen nutzen können: Cover, Verlängern, Abschnitt ersetzen, Stem-Trennung und weitere.

Endpunkt: POST /api/music/upload-source

Abrechnung: Kostenlos. Dieser Endpunkt lädt nur das Quellaudio hoch; er startet keinen Generierungsauftrag.

Empfohlene Nutzung: Das ist Schritt 1 des „zweistufigen Covers“. Laden Sie das Audio zuerst mit diesem Endpunkt hoch (kostenlos, bei Fehlschlag jederzeit wiederholbar) und speichern Sie die zurückgegebene clip_id; nachdem Sie bestätigt haben, dass der Upload erfolgreich war (status in einem abgeschlossenen Zustand), rufen Sie die Cover-aus-Quell-Clip-API auf, um das Cover zu starten — dieser Request-Body ist nur wenige hundert Bytes groß und kann daher nicht abgeschnitten werden, weil das Audio zu groß ist. Verglichen mit der Einmal-API Hochladen und covern ist diese Aufteilung robuster, wenn das Audio groß ist, das Netz instabil ist oder dasselbe Material mehrfach wiederverwendet wird (Verlängern / Ersetzen / Stem-Trennung).

Hinweise für große Uploads

Bestätigen Sie nach dem Upload immer, dass status in der Antwort bereits abgeschlossen ist, und speichern Sie die clip_id, bevor Sie zu Schritt 2 übergehen; ein fehlgeschlagener Upload wird nicht berechnet und erzeugt keinen Generierungsauftrag — einfach erneut versuchen.

file_url vor dem Upload prüfen

file_url wird vom Plattformserver selbst per HTTP heruntergeladen, nicht vom Browser. Eine URL, die in Ihrem Browser funktioniert, ist deshalb noch nicht vom Produktionsserver erreichbar.

Lokale Dateien sollten per Multipart mit dem Feld file hochgeladen werden. ByteDance-Links oder temporäre Signed URLs eignen sich für file_url nur, wenn sie öffentlich erreichbar und beim Aufruf noch gültig sind.

Vor dem Upload von einem öffentlichen Server aus ausführen:

curl -L --max-time 30 -D - -o /dev/null "https://example.com/source.mp3"

Der GET muss mit HTTP 200 enden, einen Audio-MIME-Typ liefern und nicht leer sein. Login-Seiten, HTML-Antworten sowie 401, 403, 404 oder 410 können vom Server nicht als Audio verwendet werden.

file_url download failed: HTTP 404 bedeutet meist, dass die Signatur abgelaufen ist, die Datei gelöscht wurde oder URL-Parameter fehlen.

Der Upload ist kostenlos. Wenn der Download der file_url scheitert, entstehen kein clip_id, kein Song-Task und keine Kosten; eine Rückerstattung ist daher nicht erforderlich.

Anfrageparameter

Headers

Für JSON-Anfragen:

Setzen Sie Content-Type bei multipart-Anfragen nicht manuell; der Client erzeugt ihn automatisch.

Body-Parameter

JSON-Beispielanfrage

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "upload_type": "file_upload"
  }'

multipart-Beispielanfrage

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.mp3" \
  -F "file_name=source.mp3" \
  -F "upload_type=file_upload" \
  -F "model=suno-v6"

import requests

with open("source.mp3", "rb") as audio:
    response = requests.post(
        "https://www.suno-api.io/api/music/upload-source",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "file_name": "source.mp3",
            "upload_type": "file_upload",
            "model": "suno-v6",
        },
        files={"file": ("source.mp3", audio, "audio/mpeg")},
        timeout=300,
    )

response.raise_for_status()
print(response.json())

Antwort

{
  "clip_id": "uploaded_clip_id",
  "status": "complete",
  "title": "source.mp3",
  "image_url": "https://...",
  "audio_url": "https://...",
  "display_tags": "pop, vocal",
  "inferred_description": "uploaded source audio",
  "clip_metadata": {}
}