API przesyłania dźwięku źródłowego

Zaktualizowano 2026-09-18 · zespół Suno-API

Opis punktu końcowego

Przesyłanie dźwięku źródłowego zamienia lokalny lub zdalny plik audio w clip źródłowy, którego mogą użyć kolejne funkcje: cover, przedłużanie, zamiana fragmentu, rozdzielanie i inne.

Punkt końcowy: POST /api/music/upload-source

Rozliczenie: Bezpłatne. Ten punkt końcowy tylko przesyła dźwięk źródłowy; nie rozpoczyna zadania generowania.

Zalecane użycie: to krok 1 «coveru dwuetapowego». Najpierw prześlij dźwięk tym punktem końcowym (bezpłatnie, a w razie niepowodzenia możesz ponawiać w dowolnym momencie) i zapisz zwrócony clip_id; po potwierdzeniu, że przesyłanie się powiodło (status w stanie ukończonym), wywołaj API coveru na podstawie clipu źródłowego, aby rozpocząć cover — ciało tego żądania ma tylko kilkaset bajtów, więc nie zostanie ucięte w tranzycie z powodu zbyt dużego pliku audio. W porównaniu z jednorazowym API „prześlij i zrób cover" taki podział jest stabilniejszy, gdy dźwięk jest duży, sieć niestabilna albo ten sam materiał ma być użyty wielokrotnie (przedłużanie / zamiana / rozdzielanie).

Wskazówki dla dużych plików

Po zakończeniu przesyłania zawsze potwierdź, że status w odpowiedzi jest już stanem ukończonym, i zapisz clip_id, zanim przejdziesz do kroku 2; nieudane przesyłanie nie jest rozliczane i nie tworzy zadania generowania — wystarczy ponowić.

Sprawdź file_url przed przesłaniem

To nasz serwer pobiera file_url przez HTTP, a nie przeglądarka. Działający w przeglądarce URL nie musi być dostępny z serwerów produkcyjnych.

Dla plików lokalnych używaj wysyłania multipart z polem file. Nie używaj file_url dla linków ByteDance ani tymczasowych podpisanych URL, chyba że są publicznie dostępne i nadal ważne podczas wysyłania żądania.

Uruchom to na publicznym serwerze przed wysłaniem żądania uploadu:

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

Żądanie GET musi zakończyć się HTTP 200, zwrócić typ MIME audio i zawierać dane. Strony logowania, HTML oraz kody 401, 403, 404 i 410 nie mogą być użyte przez serwer.

file_url download failed: HTTP 404 zwykle oznacza wygaśnięcie podpisu, usunięcie pliku lub niepełne parametry URL.

To przesyłanie jest bezpłatne. Jeśli pobranie file_url się nie powiedzie, nie powstaje clip_id, zadanie utworu ani wywołanie generowania i nie pobierana jest opłata; zwrot nie jest potrzebny.

Parametry żądania

Headers

Dla żądań JSON:

W żądaniach multipart nie ustawiaj Content-Type ręcznie; klient generuje go automatycznie.

Parametry body

Przykład żądania JSON

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"
  }'

Przykład żądania multipart

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())

Odpowiedź

{
  "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": {}
}