Genererings-API i enkelt läge

Uppdaterad 2026-09-18 · Suno-API-teamet

Beskrivning av ändpunkten

Generering i enkelt läge gör en beskrivning på en mening till en färdig låt. Tjänsten skriver text, melodi, arrangemang och sång utifrån din beskrivning.

Ändpunkt: POST /api/music/create

Fakturering: Betalt, för närvarande som standard 0,6 ¥ per anrop. Varje anrop ger oftast 2 låtar; det faktiskt debiterade beloppet följer den aktuella prisinställningen i backoffice.

Max Mode / Variety: den här ändpunkten stöder de valfria parametrarna max_mode och variety (0-4). Med max_mode på debiteras anropet till dubbelt pris (0,6 ¥ → 1,2 ¥ per anrop); variety kostar inget extra. Vad de betyder och hur de skickas står i avsnittet "Avancerade parametrar" i Översikt över det nya API:t.

Rekommenderad modell: suno-v6

Väntetider och timeouts (viktigt): detta är en synkron ändpunkt — beställningen accepteras och lämnas till generering först när svaret kommer. Mätt: de flesta anrop svarar på 1-3 sekunder, omkring 10% tar längre än 30 sekunder och det längsta är cirka 230 sekunder. Ställ in klientens timeout på 300 sekunder eller mer; inget svar betyder inte att inget genererades, och försök inte igen direkt efter en timeout (det duplicerar beställningen och debiterar igen). Om anslutningen bröts, kontrollera senare med GET /api/music/songs. Se "Väntetider och timeout-inställningar" i Översikt över det nya API:t.

Begäransparametrar

Headers

Brödtextparametrar

Exempelbegäranden

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": "en pigg mandarinpoplåt om sommaren vid havet",
    "instrumental": false,
    "wait_completion": false
  }'

Referensmaterial references (valfritt)

references är en array som hänger "referensmaterial" på den här genereringen. Den är helt valfri (utelämnad beter sig precis som förut), och du kan hänga på en enda sort eller valfri kombination.

Elementtyper

Regler

• Ordningen på referenslåtarna är deras semantiska ordning: skicka dem i den ordning du vill (till exempel "melodi från den första, sång från den andra").
• style_prompt / lyrics / duration_s får alla utelämnas; plattformen fyller i dem från låtinformationen och det du skickar gäller.
• I rent instrumentella låtar får lyrics vara "" eller "[Instrumental]".
• Referensbilder stöder jpeg / png / webp, upp till 10MB vardera, skickade med brödtexten som base64.
• När du hänger på flera referenslåtar, använd också accept_mode=async (se "Kvittoläge för mottagande" ovan): tjänsten måste förbereda materialet först, så en synkron väntan kan bli lång.

Exempel: två referenslåtar

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": "slå ihop de här idéerna till en låt",
    "references": [
      { "type": "song", "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
      { "type": "song", "song_id": "a90438d2-35fc-4443-88f4-56531e6e5d24" }
    ]
  }'

Exempel: referenslåt + äldre röst

{
  "model": "suno-v6",
  "description": "sjung de här idéerna med den här rösten",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "voice", "voice_id": "5813cbe1-36f1-414a-a9a8-4d399dfeb292" }
  ]
}

Exempel: referenslåt + referensbild

{
  "model": "suno-v6",
  "description": "fånga stämningen i den här bilden",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "image", "base64": "data:image/jpeg;base64,/9j/4AAQ..." }
  ]
}

Parameterfel

De här fallen ger HTTP 400, blockerade före all fakturering, så de kostar inget:

Siffran i references[0] är elementets index i arrayen, så det felande elementet är lätt att hitta.

Svar

En array av låtar, oftast med 2 uppgifter eller låtar.

[
  {
    "song_id": "clip_id",
    "song_title": "Sommarvind från havet",
    "status": "pending",
    "description": "en pigg mandarinpoplåt om sommaren vid havet",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Kvittoläge för mottagande (valfritt, rekommenderas för klienter som inte ska hålla långa anslutningar)

Som standard är ändpunkten synkron: att svaret kommer är det som betyder att beställningen accepterades, och uppmätta väntetider kan nå omkring 230 sekunder. Om din klient inte ska hålla en lång anslutning, aktivera kvittoläget för mottagande — båda fungerar:

• lägg till "accept_mode": "async" i begärans brödtext
• lägg till headern X-Accept-Mode: async

Med det på svarar ändpunkten omedelbart med HTTP 202, vilket bara betyder "mottagen och i genereringskön", medan genereringen fortsätter i bakgrunden:

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

Mottagningsfasen returnerar ingen song_id. Det finns ännu inget riktigt låt-ID, och varken request_id eller tasks[].index är ett låt-ID — spara dem inte som song_id. Den riktiga song_id dyker upp i framstegsfrågan nedan.

Fråga efter mottagningsframsteg

Ändpunkt: GET /api/music/requests/{request_id} (gratis, autentiseras med samma API-nyckel)

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

Vad varje status-värde betyder:

Varje uppgift har också sin egen tasks[].status, med samma värden som API för låtfrågor: pending (lämnad, genereras), processing, completed, failed. Uppgiftsposter kan också bära title, duration och en redan registrerad audio_url; det som saknas är helt enkelt inte genererat än.

När du har den riktiga song_id fortsätter du med API för låtfrågor eller nedladdningsändpunkterna.

Python-exempel

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": "en pigg poplåt", "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

Kompatibilitet och noter

• Utan accept_mode är beteendet exakt som förut: synkron väntan, svar 200 och en array av låtar. Befintliga integrationer behöver inte ändra något.
• Den här växeln fungerar just nu bara på POST /api/music/create och POST /api/music/create/custom; övriga genereringsändpunkter stöder den ännu inte.
• Skicka också en Idempotency-Key (din egen unika sträng, ≤128 tecken): samma nyckel accepteras bara en gång, en upprepning ger samma kvitto och inget debiteras två gånger. I asynkront läge är det extra viktigt.
• Med accept_mode=async ignoreras wait_completion (kvittot kommer direkt, utan att vänta på låtarna).
• Beloppet förbrukas fortfarande i förskott när beställningen tas emot; en misslyckad generering återbetalas automatiskt i sin helhet.
• Textfältets gräns: description rymmer högst 3000 tecken (räknat i Unicode-tecken, ett Han-tecken räknas som 1). Längre text ger direkt HTTP 400, går aldrig in i genereringen och debiteras inte, och felmeddelandet anger den uppmätta längden, till exempel description must not exceed 3000 characters; received 4120. Den här ändpunkten har inga text-/stilfält; för dem se "Textfältets gräns" i Genererings-API i anpassat läge. De allmänna reglerna finns i "Gränser för textfält" i Översikt över det nya API:t.
• Utan references är beteende, pris och svar exakt som förut: befintliga integrationer behöver inte ändra något.
• När referensmaterial hänger med (särskilt flera låtar) är kvittoläget accept_mode=async att föredra framför lång synkron väntan; hur lång tid förberedelsen tar beror på mängd och källa.

Nästa steg

Om låtarna inte är klara när svaret kommer, hämta slutresultatet med API för låtfrågor.

Exempel på Node/Electron-integration

Om du integrerar standardgenerering i Electron-huvudprocessen, en Node.js-server eller en skrivbordsklient är detta det rekommenderade flödet:

1. Anropa POST /api/music/create för att skapa genereringsuppgiften.
2. Läs song_id eller id från svaret.
3. Anropa POST /api/music/query varannan sekund för att kontrollera status.
4. Betrakta genereringen som klar så snart audio_url dyker upp i resultatet.

Sluta använda de gamla sökvägarna POST /api/generate eller GET /api/clip?id=...; de tillhör inte den för närvarande rekommenderade publika integrationsytan.

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

I riktiga projekt förvarar du API-nyckeln i en servermiljövariabel, en inställning i skrivbordsklienten eller i säker lagring — aldrig i frontendkod och aldrig incheckad i ett arkiv.