API wzmocnionego wgrania

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

Opis punktu końcowego

Wzmocnione wgranie przyjmuje lokalny plik dźwiękowy; system wykonuje wzmocnienie w tle i tworzy kompletny, odtwarzalny utwór. Wywołanie zwraca od razu informacje o zadaniu, a klient odpytuje punkt końcowy wyszukiwania o postęp.

Punkt końcowy zgłoszenia: POST /api/music/enhanced-upload

Wyszukanie jednego zadania: GET /api/music/enhanced-upload/:id

Anulowanie zadania: POST /api/music/enhanced-upload/:id/cancel

Wyszukanie listy: GET /api/music/enhanced-upload

Rozliczenie: 10 ¥ za wywołanie, pobierane z góry według stałej ceny suno-enhanced-upload. Jeśli zadanie się nie powiedzie lub zostanie anulowane na dozwolonym etapie, pobrana z góry kwota jest automatycznie zwracana. Faktycznie pobierana kwota zależy od bieżącej konfiguracji cen w panelu administracyjnym.

Przebieg wywołań

1. Wywołaj POST /api/music/enhanced-upload, aby przesłać plik dźwiękowy.
2. Zapisz zwrócone task_id.
3. Wywołaj GET /api/music/enhanced-upload/:id, aby sprawdzić postęp i wynik.
4. Gdy Suno zakończy finalne renderowanie, usługa używa konta Suno przypisanego do tego zadania, wywołuje punkt końcowy autoryzowanego pobierania Studio i zapisuje MP3 w usłudze mediów CN2.
5. Zadanie staje się completed dopiero gdy zasób CN2 jest gotowy; wtedy adres dźwięku CDN odczytuje się z audio_url w odpowiedzi.

/api/forbidden to adres zastępczy, który może pojawić się w metadanych Suno Studio; nie jest zasobem do odtwarzania ani pobierania. Nigdy nie jest zwracany klientowi ani nie służy jako podstawa uznania zadania za zakończone. Jeśli renderowanie się zakończyło, a CN2 wciąż się przygotowuje, punkt końcowy nadal zwraca processing i nie zwraca audio_url; klient powinien kontynuować odpytywanie i nie traktować pustego adresu jako błędu.

Wysłanie wzmocnionego wgrania

Headers

Parametry formularza

Przykładowe żądanie

Poniższy przykład używa tego samego sposobu wywołania co przy walidacji na produkcji, ale klucz API zastąpiono wartością zastępczą.

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"

Odpowiedź

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

Wyszukanie jednego zadania

Przykładowe żądanie

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

Przykładowa odpowiedź w trakcie przetwarzania

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

Przykładowa odpowiedź po zakończeniu

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

Anulowanie zadania

Anulowanie jest możliwe tylko wtedy, gdy zarówno zadanie, jak i workflow backendu są jeszcze na etapie queued. Gdy zadanie wejdzie w leasing, running, processing lub zostanie ukończone, anulowanie nie jest możliwe.

Przykładowe żądanie

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"

Odpowiedź

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

Jeśli zadanie już rozpoczęło przetwarzanie, punkt końcowy zwróci:

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

Wyszukanie listy zadań

Punkt końcowy listy zwraca wyłącznie zadania wzmocnionego wgrania użytkownika, do którego należy bieżący klucz API; zwykłe generowanie, covery i przedłużanie nie są mieszane.

Parametry zapytania

Przykładowe żądanie

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"

Odpowiedź

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

Opis pól odpowiedzi

Uwagi

• Obecnie punkt końcowy obsługuje wyłącznie przesyłanie plików multipart; JSON file_url i file_base64 nie są obsługiwane.
• Przesyłany plik ma maksymalnie 80 MB.
• Punkt końcowy zgłoszenia jest asynchroniczny: odpowiedź queued oznacza, że zadanie trafiło do kolejki, a nie że dźwięk jest gotowy.
• Anulowanie dotyczy tylko zadań, które nie rozpoczęły jeszcze przetwarzania; po rozpoczęciu przetwarzania workflow konta platformy nie jest przerywany.
• Nie ujawniaj prawdziwych kluczy API w kodzie klienta.

Rozpoczęcie coveru po zakończeniu wzmocnionego wgrania

Po zakończeniu wzmocnionego wgrania możesz użyć wyniku jako clipu źródłowego i wywołać POST /api/music/generate-from-source, aby rozpocząć cover.

Uwaga: cover to punkt końcowy synchroniczny — zamówienie jest przyjmowane dopiero z nadejściem odpowiedzi, a w zmierzonych przypadkach może to potrwać do około 230 sekund. Ustaw limit czasu klienta na 300 sekund lub więcej i nie ponawiaj od razu po przekroczeniu limitu. Zobacz „Czasy oczekiwania i ustawienia limitu czasu” w Przeglądzie nowego API.

Najpierw odpytuj GET /api/music/enhanced-upload/:id, aż task.status będzie completed. Wtedy:

• task.song_id to prawdziwe ID utworu i zarazem sourceClipId, którego potrzebuje punkt końcowy coveru;
• warto przekazać task.audio_url jako sourceAudioUrl, aby serwer poradził sobie z przypadkiem, gdy clip źródłowy i konto wykonujące się różnią;
• task.task_id to jedynie ID zadania wzmocnionego wgrania i nie może być użyte jako sourceClipId;
• pending:enhanced-upload:* to identyfikator zastępczy etapu przetwarzania i nie można go użyć do coveru.

Rozpoczynając cover, użyj tego samego klucza API co przy wzmocnionym wgraniu i złóż żądanie według poniższego mapowania pól.

Pozostałe parametry (tekst, styl, tytuł, model) wypełnij zgodnie z API coveru na podstawie clipu źródłowego. Gdy punkt końcowy coveru zwróci nowe clips[].song_id, użyj POST /api/music/query, aby sprawdzić status generowania i finalny dźwięk.