API generowania w trybie prostym

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

Opis punktu końcowego

Generowanie w trybie prostym zamienia opis w jednym zdaniu w gotowy utwór. Usługa sama pisze tekst, melodię, aranżację i wokal na podstawie Twojego opisu.

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

Rozliczenie: Płatne, obecnie domyślnie 0,6 ¥ za wywołanie. Jedno wywołanie zwykle daje 2 utwory; faktycznie pobierana kwota zależy od bieżącej konfiguracji cen w panelu administracyjnym.

Max Mode / Variety: ten punkt końcowy obsługuje opcjonalne parametry max_mode i variety (0-4). Przy włączonym max_mode to wywołanie jest rozliczane po podwójnej cenie (0,6 ¥ → 1,2 ¥ za wywołanie); variety nie kosztuje nic dodatkowo. Znaczenie i sposób wysyłania opisano w sekcji „Parametry zaawansowane” Przeglądu nowego API.

Zalecany model: suno-v6

Czasy oczekiwania i limity czasu (ważne): to punkt końcowy synchroniczny — zamówienie zostaje przyjęte i przekazane do generowania dopiero, gdy przyjdzie odpowiedź. Z pomiarów: większość żądań odpowiada w 1-3 sekundy, około 10% przekracza 30 sekund, a najdłuższe trwa około 230 sekund. Ustaw limit czasu klienta na 300 sekund lub więcej; brak odpowiedzi nie oznacza, że nic nie zostało wygenerowane, a ponawianie od razu po limicie czasu duplikuje zamówienie i pobiera opłatę ponownie. Jeśli połączenie się zerwało, sprawdź później przez GET /api/music/songs. Zobacz „Czasy oczekiwania i ustawienia limitu czasu” w Przeglądzie nowego API.

Parametry żądania

Headers

Parametry treści

Przykłady żądania

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "description": "żywiołowa mandaryńska piosenka pop o lecie nad morzem",
    "instrumental": false,
    "wait_completion": false
  }'

Materiał referencyjny references (opcjonalnie)

references to tablica, która doczepia do tego generowania „materiał referencyjny”. Jest całkowicie opcjonalna (pominięcie działa dokładnie jak wcześniej) i można doczepić jeden rodzaj lub dowolną kombinację.

Typy elementów

Zasady

• Kolejność utworów referencyjnych to ich kolejność znaczeniowa: podaj je w zamierzonej kolejności (na przykład „melodia z pierwszego, wokal z drugiego”).
• style_prompt / lyrics / duration_s można pominąć; platforma uzupełni je z informacji o utworze, a to, co wyślesz, ma pierwszeństwo.
• W utworach czysto instrumentalnych lyrics może być "" lub "[Instrumental]".
• Obrazy referencyjne obsługują jpeg / png / webp, do 10 MB każdy, przesyłane razem z treścią jako base64.
• Przy kilku utworach referencyjnych użyj dodatkowo accept_mode=async (patrz „Tryb potwierdzenia odbioru” powyżej): usługa musi najpierw przygotować materiał, więc synchroniczne oczekiwanie może być długie.

Przykład: dwa utwory referencyjne

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "description": "połącz te pomysły w jeden utwór",
    "references": [
      { "type": "song", "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
      { "type": "song", "song_id": "a90438d2-35fc-4443-88f4-56531e6e5d24" }
    ]
  }'

Przykład: utwór referencyjny + stary głos

{
  "model": "suno-v6",
  "description": "zaśpiewaj te pomysły tym głosem",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "voice", "voice_id": "5813cbe1-36f1-414a-a9a8-4d399dfeb292" }
  ]
}

Przykład: utwór referencyjny + obraz referencyjny

{
  "model": "suno-v6",
  "description": "oddaj nastrój tego obrazu",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "image", "base64": "data:image/jpeg;base64,/9j/4AAQ..." }
  ]
}

Błędy parametrów

Te przypadki zwracają HTTP 400, blokowane przed jakimkolwiek rozliczeniem, więc nic nie kosztują:

Liczba w references[0] to indeks tego elementu w tablicy, więc błędny element łatwo znaleźć.

Odpowiedź

Tablica utworów, zwykle z 2 zadaniami lub utworami.

[
  {
    "song_id": "clip_id",
    "song_title": "Letnia bryza morska",
    "status": "pending",
    "description": "żywiołowa mandaryńska piosenka pop o lecie nad morzem",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Tryb potwierdzenia odbioru (opcjonalny, zalecany klientom, które nie powinny trzymać długich połączeń)

Domyślnie ten punkt końcowy jest synchroniczny: przyjście odpowiedzi oznacza, że zamówienie zostało przyjęte, a mierzone czasy oczekiwania mogą sięgać około 230 sekund. Jeśli klient nie powinien trzymać długiego połączenia, włącz tryb potwierdzenia odbioru — wystarczy jedno z dwóch:

• dodaj "accept_mode": "async" do treści żądania
• dodaj nagłówek X-Accept-Mode: async

Po włączeniu punkt końcowy natychmiast zwraca HTTP 202, co oznacza tylko „przyjęte i w kolejce do generowania”, a generowanie trwa w tle:

{
  "success": true,
  "data": {
    "request_id": "ac_20260920092714315816800d76fv3nq",
    "status": "queued",
    "accepted_at": 1789896434,
    "pre_consumed_quota": 300000,
    "tasks": [
      { "index": 0, "status": "queued" },
      { "index": 1, "status": "queued" }
    ]
  }
}

Na etapie przyjęcia nie zwraca się song_id. Prawdziwy identyfikator utworu jeszcze nie istnieje, a ani request_id, ani tasks[].index nie są identyfikatorem utworu — nie zapisuj ich jako song_id. Prawdziwy song_id pojawia się w poniższym zapytaniu o postęp.

Zapytanie o postęp przyjęcia

Punkt końcowy: GET /api/music/requests/{request_id} (bezpłatnie, uwierzytelnianie tym samym kluczem API)

curl "https://www.suno-api.io/api/music/requests/ac_20260920092714315816800d76fv3nq" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "request_id": "ac_20260920092714315816800d76fv3nq",
    "status": "processing",
    "tasks": [
      { "index": 0, "status": "processing", "song_id": "f3fa09f5-3d55-4953-826c-0d23f043ec57" },
      { "index": 1, "status": "processing", "song_id": "5fcafe3e-3fae-4d64-8f66-c01bc027b0c3" }
    ]
  }
}

Co oznacza każda wartość status:

Każde zadanie ma też własne tasks[].status, o tych samych wartościach co w API zapytań o utwory: pending (przekazane, generowane), processing, completed, failed. Elementy zadań mogą też zawierać title, duration oraz już zarejestrowany audio_url; brak oznacza po prostu, że jeszcze nie wygenerowano.

Gdy masz prawdziwy song_id, kontynuuj przez API zapytań o utwory lub punkty końcowe pobierania.

Przykład w Pythonie

import time
import requests

BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}

accepted = requests.post(
    f"{BASE}/api/music/create",
    headers={**HEADERS, "Idempotency-Key": "your-own-unique-key"},
    json={"description": "żywiołowa piosenka pop", "model": "suno-v6", "accept_mode": "async"},
    timeout=300,
).json()["data"]

request_id = accepted["request_id"]
while True:
    time.sleep(5)
    progress = requests.get(
        f"{BASE}/api/music/requests/{request_id}", headers=HEADERS, timeout=60
    ).json()["data"]
    if progress["status"] in ("completed", "failed"):
        print(progress)
        break

Zgodność i uwagi

• Bez accept_mode zachowanie jest dokładnie takie jak wcześniej: synchroniczne oczekiwanie, odpowiedź 200 i tablica utworów. Istniejące integracje nie muszą nic zmieniać.
• Ten przełącznik działa obecnie tylko na POST /api/music/create i POST /api/music/create/custom; pozostałe punkty końcowe generowania jeszcze go nie obsługują.
• Wyślij także Idempotency-Key (własny unikalny ciąg, ≤128 znaków): ten sam klucz zostanie przyjęty tylko raz, powtórzenie zwraca to samo potwierdzenie i nie ma podwójnego obciążenia. W trybie asynchronicznym ma to szczególne znaczenie.
• Przy accept_mode=async parametr wait_completion jest ignorowany (potwierdzenie wraca natychmiast, bez czekania na utwory).
• Kwota nadal jest pobierana z góry przy przyjęciu zamówienia; nieudane generowanie jest automatycznie w pełni zwracane.
• Limit pola tekstowego: description mieści maksymalnie 3000 znaków (liczone w znakach Unicode, jeden znak han liczy się jako 1). Dłuższy tekst od razu zwraca HTTP 400, nie trafia do generowania i nie jest rozliczany, a komunikat błędu podaje zmierzoną długość, na przykład description must not exceed 3000 characters; received 4120. Ten punkt końcowy nie ma pól tekstu/stylu; dla nich zobacz „Limit pola tekstowego” w API generowania w trybie niestandardowym. Ogólne zasady są w „Limity pól tekstowych” Przeglądu nowego API.
• Bez references zachowanie, cena i odpowiedź są dokładnie takie jak wcześniej: istniejące integracje nie muszą nic zmieniać.
• Gdy dołączony jest materiał referencyjny (zwłaszcza kilka utworów), preferuj tryb potwierdzenia accept_mode=async zamiast długiego synchronicznego oczekiwania; czas przygotowania materiału zależy od jego ilości i źródła.

Następne kroki

Jeśli utwory nie są gotowe w chwili odpowiedzi, pobierz wynik końcowy przez API zapytań o utwory.

Przykład integracji w Node/Electron

Jeśli wbudowujesz standardowe generowanie w proces główny Electrona, serwer Node.js lub klienta desktopowego, zalecany przebieg jest taki:

1. Wywołaj POST /api/music/create, aby utworzyć zadanie generowania.
2. Odczytaj song_id lub id z odpowiedzi.
3. Co 2 sekundy wywołuj POST /api/music/query, aby sprawdzić status.
4. Uznaj generowanie za zakończone, gdy tylko w wyniku pojawi się audio_url.

Nie używaj już starych ścieżek POST /api/generate ani GET /api/clip?id=...; nie należą do obecnie zalecanej publicznej powierzchni integracji.

const http = require('http');
const https = require('https');

const BASE_URL = 'https://www.suno-api.io';
const MODEL = 'suno-v6';
const POLL_INTERVAL_MS = 2000;
const MAX_POLL_ATTEMPTS = 60;

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function requestJson(urlString, apiKey, body) {
  const url = new URL(urlString);
  const transport = url.protocol === 'https:' ? https : http;
  const payload = JSON.stringify(body);

  return new Promise((resolve, reject) => {
    const req = transport.request(
      {
        method: 'POST',
        hostname: url.hostname,
        port: url.port || undefined,
        path: `${url.pathname}${url.search}`,
        headers: {
          Authorization: `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
          'Content-Length': Buffer.byteLength(payload),
        },
      },
      (res) => {
        let raw = '';

        res.setEncoding('utf8');
        res.on('data', (chunk) => {
          raw += chunk;
        });
        res.on('end', () => {
          const data = raw ? JSON.parse(raw) : {};

          if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
            reject(new Error(`Suno API request failed: HTTP ${res.statusCode} ${raw}`));
            return;
          }

          resolve(data);
        });
      }
    );

    req.on('error', reject);
    req.write(payload);
    req.end();
  });
}

function getPayload(response) {
  return response && response.data !== undefined ? response.data : response;
}

function toSongList(payload) {
  if (Array.isArray(payload)) return payload;
  if (Array.isArray(payload?.songs)) return payload.songs;
  if (Array.isArray(payload?.clips)) return payload.clips;
  return payload ? [payload] : [];
}

function collectSongIds(createResponse) {
  return toSongList(getPayload(createResponse))
    .map((song) => song.song_id || song.id)
    .filter(Boolean);
}

async function generateSunoSong({ apiKey, description, instrumental = false }) {
  const createResponse = await requestJson(`${BASE_URL}/api/music/create`, apiKey, {
    description,
    model: MODEL,
    instrumental,
    wait_completion: false,
  });

  const songIds = collectSongIds(createResponse);
  if (songIds.length === 0) {
    throw new Error(`Suno API did not return song ids: ${JSON.stringify(createResponse)}`);
  }

  for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt += 1) {
    await sleep(POLL_INTERVAL_MS);

    const queryResponse = await requestJson(`${BASE_URL}/api/music/query`, apiKey, {
      song_ids: songIds,
      model: MODEL,
    });

    const songs = toSongList(getPayload(queryResponse));
    const completed = songs.find((song) => song.audio_url);

    if (completed) {
      return {
        audioUrl: completed.audio_url,
        title: completed.song_title || completed.title || 'Suno Song',
        duration: completed.duration,
      };
    }

    const allFailed = songs.length > 0 && songs.every((song) =>
      ['failed', 'error', 'rejected'].includes(String(song.status || '').toLowerCase())
    );

    if (allFailed) {
      throw new Error(`Suno generation failed: ${JSON.stringify(songs)}`);
    }
  }

  throw new Error('Suno generation timed out after 120 seconds. Please query again later.');
}

// Usage:
// generateSunoSong({
//   apiKey: process.env.SUNO_API_KEY,
//   description: 'A bright pop song about the ocean in summer',
// }).then(console.log).catch(console.error);

W rzeczywistych projektach trzymaj klucz API w zmiennej środowiskowej serwera, w ustawieniach klienta desktopowego lub w bezpiecznym magazynie — nigdy w kodzie front-endowym i nigdy w repozytorium.