API zapytań o utwory i historii

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

Ta strona obejmuje trzy darmowe punkty końcowe zapytań:

Jeśli użyłeś na punkcie końcowym generowania trybu potwierdzenia odbioru (accept_mode=async), w ręku masz numer potwierdzenia, a nie identyfikator utworu. Śledź postęp przez GET /api/music/requests/{request_id} i wróć do punktów końcowych z tej strony, gdy uzyskasz prawdziwy song_id. Zobacz „Tryb potwierdzenia odbioru” w API generowania w trybie prostym.

Uwierzytelnianie i zakres danych

Wszystkie trzy punkty końcowe uwierzytelniają się tym samym kluczem API:

Authorization: Bearer YOUR_API_KEY

Historia utworów jest izolowana według user_id, do którego należy klucz API. Kilka kluczy utworzonych w ramach tego samego konta głównego może czytać historię tego konta, ale nie historię innego użytkownika ani konta podstrony.

Punkty końcowe historii zwracają wyłącznie naprawdę wygenerowane utwory. Wykluczone są:

• rekordy zastępcze generowania zaczynające się od pending:;
• wgrywanie źródłowego audio i rekordy ulepszonego wgrywania;
• wyniki pośrednie, takie jak rozdzielenie wokalu i akompaniamentu oraz stem-y;
• utwory innych użytkowników lub kont podstron.

1. Zapytanie o status generowania

Sprawdza bieżący status i wynik końcowy jednego lub kilku identyfikatorów utworów.

Punkt końcowy: POST /api/music/query

Rozliczenie: Bezpłatnie.

Headers

Parametry treści

Przykładowe żądanie

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

Przykładowa odpowiedź

[
  {
    "song_id": "clip_id_1",
    "song_title": "Tytuł utworu",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Treść tekstu",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Uwagi o zgodności

Starsza dokumentacja może pokazywać song_ids jako tablicę. Obecnie zalecany jest ciąg rozdzielony przecinkami, co odpowiada rzeczywistemu wywołaniu punktu końcowego.

song_ids musi zawierać prawdziwe identyfikatory utworów. Identyfikator zastępczy zaczynający się od pending: nie jest końcowym song_id i nie działa tutaj; odpytywanie wyłącznie identyfikatorów zastępczych może zwrócić pustą tablicę [].

model, model_version lub platformowe model_name w odpowiedzi mogą zachować wartości historyczne. Nowe zadania powinny używać suno-v6, suno-v6-wild lub suno-v6-mini; od suno-v2 do suno-v5-5 zostały wycofane, a obecność tych nazw w historii nie oznacza, że model nadal przyjmuje zgłoszenia.

Dopóki zadanie ma status pending, submitted lub processing, pola audio_url, video_url i cover_url mogą być puste — to normalne dla niedokończonego zadania. Nie wyciągaj wniosku o błędzie wyłącznie z pustego adresu; kieruj się status i zapytaj ponownie, gdy status będzie zakończony. Tylko jeśli status jest zakończony, a adresy nadal puste, warto zgłosić się do wsparcia z song_id.

⚠️ Adresy audio żyją 7 dni — przenieś pliki na czas

Zwracane tu audio_url, video_url (oraz inne adresy multimediów, np. WAV) są serwowane z magazynu obiektów platformy i domyślnie wygasają po 7 dniach: pliki są odzyskiwane, a stary adres zwraca 404.

• W ciągu tych 7 dni przenieś pliki do własnego magazynu; nie traktuj adresu jako trwałego linku.
• Wygasły adres nie wymaga ponownego generowania utworu i nie jest ponownie rozliczany: wywołaj ten punkt końcowy (POST /api/music/query) ponownie, aby otrzymać nowy, ważny adres tego utworu.

2. Zapytanie o historię utworów konta

Listuje utwory utworzone przez konto główne, do którego należy bieżący klucz API. Przydatne do własnej listy utworów, selektora lub strony historii.

Punkt końcowy: GET /api/music/songs

Rozliczenie: Bezpłatnie.

Parametry zapytania

Wyniki są sortowane malejąco według created_at i wewnętrznego identyfikatora rekordu, dzięki czemu kolejność stron jest stabilna.

Jak odnaleźć zgłoszenie, które przekroczyło limit czasu: punkty końcowe generowania nie dają odpowiedzi pośredniej przed przyjęciem. Jeśli klient przekroczył limit czasu lub połączenie się zerwało przy zgłaszaniu, zamówienie może być już przyjęte i generowane. Zajrzyj do tego punktu końcowego (najnowsze najpierw): przyjęte utwory pojawiają się normalnie na liście. Zgłoś ponownie tylko po potwierdzeniu, że utworu naprawdę nie ma — inaczej zapłacisz dwa razy. Zobacz „Czasy oczekiwania i ustawienia limitu czasu” w Przeglądzie nowego API.

Przykładowe żądanie

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Przykładowa odpowiedź

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "Miasto nocą",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

Pola odpowiedzi

Punkt końcowy listy nie zwraca promptów, pól rozliczeniowych, informacji o koncie ani surowych odpowiedzi. Po prompty i parametry generowania sięgnij do punktu końcowego szczegółów utworu.

3. Zapytanie o parametry generowania

Sprawdza prompt, styl, model i utwór źródłowy zachowane przez platformę przy generowaniu danego utworu.

Punkt końcowy: GET /api/music/songs/:song_id

Rozliczenie: Bezpłatnie.

Można czytać tylko utwory konta głównego, do którego należy bieżący klucz API. Utwory innych użytkowników lub kont podstron są jednolicie traktowane jako „nie znaleziono utworu”.

Parametr ścieżki

Przykładowe żądanie

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Przykładowa odpowiedź

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "Miasto nocą",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "ulice miasta po deszczu, tekst o ponownym spotkaniu",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "Miasto nocą",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

Pola parameters

Pole prompt_view (podgląd promptu, dodane 2026-09-28)

prompt_view to znormalizowana struktura przeznaczona do „podglądu promptu”: porządkuje dane w stałe sekcje zależnie od typu generowania, więc klient nie musi już sam decydować, które pole pokazać. To pole wyłącznie dodane — stare pola (parameters, parameter_retention) zachowują nazwę i znaczenie, a klienci, którzy nie analizują nowego pola, nie są w ogóle dotknięci.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Tryb niestandardowy",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Czwarta nad ranem#701f37", "title_base": "Czwarta nad ranem", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "elektronika guochao, głęboki subbas, retro syntezator",
    "style_tags": "elektronika guochao, głęboki subbas, retro syntezator",
    "style_source": "user", "lyrics": "...",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

Pola, które mogą pojawić się w extended: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, oraz grupa efektów dźwiękowych sound_type / sound_bpm / sound_key / sound_loop. Puste wartości nigdy nie są zwracane.

Trzy zasady prezentacji (stosuj je, zamiast zgadywać):

1. Rozróżniaj pochodzenie stylu: przy style_source=suno_derived pokazuj „styl (wyprowadzony przez Suno z Twojego opisu)”, nigdy „Twój styl”;
2. Wewnętrzne prompty nigdy się nie pojawiają: typy coveru z głosem zwracają tylko wpisane przez użytkownika 【wymagania stylu】/【wymagania coveru】; stała konstrukcja, którą składamy dla modelu, nie występuje w żadnym polu (dane historyczne są oczyszczone tak samo);
3. Nie zgaduj brakujących parametrów: jeśli czegoś nie ma w extended, nie zostało wtedy zapisane — wyjaśnij to przez retention.

Uwagi o zachowywaniu parametrów

parameter_retention rozdziela „przekazano jawnie pustą wartość” od „pola nigdy historycznie nie zapisano”:

• core_parameters_available: czy istnieje główny rekord zadania; przy poprawnym zapytaniu o szczegóły zwykle true;
• extended_parameters_available: czy znaleziono powiązany rekord rozszerzonego zadania muzycznego;
• sources: z których tabel danych pochodzi ta odpowiedź;
• unavailable_fields: pola, których nie da się wiarygodnie odtworzyć z historii; zwracają null w parameters.

Zwykłe utwory historyczne zwykle zachowały prompt, styl, bieżący tytuł, model, typ generowania i utwór źródłowy, ale nie zapisały osobno wszystkich parametrów zaawansowanych. Platforma nigdy nie zgaduje brakujących wartości z generation_type.

Niektóre rozszerzone zadania muzyczne zachowały także oryginalny prompt, styl, tytuł, model oraz dodatkowo custom_mode, negative_tags, vocal_gender, style_weight i weirdness_constraint. Nawet gdy rekord rozszerzony istnieje, instrumental, lyrics_mode i wait_audio mogą pozostać nieodtwarzalne.

Tytuły mogą być później zmieniane przez użytkownika. Gdy zwykłe zadanie historyczne nie zachowało osobnego oryginalnego tytułu, parameters.title może być bieżącym tytułem; gdy istnieje rekord zadania rozszerzonego, pierwszeństwo ma zapisany tam oryginalny tytuł generowania.

Nie znaleziono lub brak uprawnień

Błędy biznesowe używają jednolitej koperty odpowiedzi. Gdy utwór nie istnieje lub nie należy do bieżącego konta:

{
  "success": false,
  "message": "song not found"
}

Ten błąd biznesowy jest obecnie zwracany z HTTP 200, więc wynik oceniaj po polu success. Brakujący, nieprawidłowy, wygasły lub wyłączony klucz API zwraca HTTP 401.

Uwagi o bezpieczeństwie

Punkty końcowe historii i szczegółów nigdy nie zwracają:

• kluczy API ani identyfikatorów tokenów;
• pól limitu, rozliczeń i zwrotów;
• informacji o koncie ani surowych odpowiedzi;
• wewnętrznych kluczy magazynu obiektów;
• błędów administratora i błędów zasobów wewnętrznych.