Generatie-API in eenvoudige modus

Bijgewerkt op 2026-09-18 · Suno-API-team

Beschrijving van het endpoint

Generatie in eenvoudige modus maakt van een beschrijving van één zin een compleet nummer. De dienst schrijft tekst, melodie, arrangement en zang op basis van uw beschrijving.

Endpoint: POST /api/music/create

Facturering: Betaald, momenteel standaard 0,6 ¥ per aanroep. Elke aanroep levert meestal 2 nummers op; het werkelijk gefactureerde bedrag volgt de huidige prijsconfiguratie in de back-office.

Max Mode / Variety: dit endpoint ondersteunt de optionele parameters max_mode en variety (0-4). Met max_mode aan wordt deze aanroep tegen het dubbele tarief gefactureerd (0,6 ¥ → 1,2 ¥ per aanroep); variety kost niets extra. Wat ze betekenen en hoe u ze verstuurt, staat in de sectie "Geavanceerde parameters" van het Overzicht van de nieuwe API.

Aanbevolen model: suno-v6

Wachttijden en timeouts (belangrijk): dit is een synchroon endpoint — de opdracht wordt pas geaccepteerd en aan generatie overgedragen wanneer het antwoord binnenkomt. Gemeten: de meeste verzoeken antwoorden in 1-3 seconden, ongeveer 10% duurt langer dan 30 seconden en de langste is ongeveer 230 seconden. Zet de client-timeout op 300 seconden of meer; geen antwoord betekent niet dat er niets is gegenereerd, en probeer niet direct na een timeout opnieuw (dat dupliceert de opdracht en rekent opnieuw af). Als de verbinding wegviel, controleer later met GET /api/music/songs. Zie "Wachttijden en timeout-instellingen" in het Overzicht van de nieuwe API.

Verzoekparameters

Headers

Body-parameters

Voorbeeldverzoeken

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": "een vrolijk Mandarijns popnummer over de zomer aan zee",
    "instrumental": false,
    "wait_completion": false
  }'

Referentiemateriaal references (optioneel)

references is een array die "referentiemateriaal" aan deze generatie hangt. Het is volledig optioneel (weglaten gedraagt zich precies als voorheen), en u kunt één soort of elke combinatie aanhangen.

Elementtypen

Regels

• De volgorde van de referentienummers is hun semantische volgorde: geef ze in de gewenste volgorde mee (bijvoorbeeld "melodie van het eerste, zang van het tweede").
• style_prompt / lyrics / duration_s mogen allemaal ontbreken; het platform vult ze aan uit de nummerinformatie en wat u stuurt, geldt.
• Bij puur instrumentale nummers mag lyrics "" of "[Instrumental]" zijn.
• Referentieafbeeldingen ondersteunen jpeg / png / webp, elk tot 10MB, als base64 met de body meegestuurd.
• Gebruik bij meerdere referentienummers ook accept_mode=async (zie "Ontvangstbewijsmodus" hierboven): de dienst moet het materiaal eerst voorbereiden, dus synchroon wachten kan lang duren.

Voorbeeld: twee referentienummers

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": "voeg deze ideeën samen tot één nummer",
    "references": [
      { "type": "song", "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
      { "type": "song", "song_id": "a90438d2-35fc-4443-88f4-56531e6e5d24" }
    ]
  }'

Voorbeeld: referentienummer + oude stem

{
  "model": "suno-v6",
  "description": "zing deze ideeën met deze stem",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "voice", "voice_id": "5813cbe1-36f1-414a-a9a8-4d399dfeb292" }
  ]
}

Voorbeeld: referentienummer + referentieafbeelding

{
  "model": "suno-v6",
  "description": "vang de sfeer van deze afbeelding",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "image", "base64": "data:image/jpeg;base64,/9j/4AAQ..." }
  ]
}

Parameterfouten

Deze gevallen geven HTTP 400, geblokkeerd vóór enige facturering, dus ze kosten niets:

Het getal in references[0] is de index van dat element in de array, dus het foutieve element is makkelijk te vinden.

Antwoord

Een array van nummers, meestal met 2 taken of nummers.

[
  {
    "song_id": "clip_id",
    "song_title": "Zomerzeewind",
    "status": "pending",
    "description": "een vrolijk Mandarijns popnummer over de zomer aan zee",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Ontvangstbewijsmodus (optioneel, aanbevolen voor clients die geen lange verbindingen mogen houden)

Standaard is dit endpoint synchroon: het binnenkomen van het antwoord betekent dat de opdracht is geaccepteerd, en gemeten wachttijden kunnen ongeveer 230 seconden bereiken. Als uw client geen lange verbinding mag houden, schakelt u de ontvangstbewijsmodus in — beide manieren werken:

• "accept_mode": "async" toevoegen aan de request body
• de header X-Accept-Mode: async toevoegen

Daarmee antwoordt het endpoint onmiddellijk met HTTP 202, wat alleen "geaccepteerd en in de generatiewachtrij" betekent, terwijl de generatie op de achtergrond doorloopt:

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

De acceptatiefase geeft geen song_id terug. Er bestaat nog geen echt nummer-ID, en noch request_id noch tasks[].index is een nummer-ID — sla ze niet op als song_id. De echte song_id verschijnt in de voortgangsopvraging hieronder.

De acceptatievoortgang opvragen

Endpoint: GET /api/music/requests/{request_id} (gratis, authenticatie met dezelfde API-sleutel)

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

Wat elke status-waarde betekent:

Elke taak heeft ook zijn eigen tasks[].status, met dezelfde waarden als de API voor nummeropvraging: pending (overgedragen, wordt gegenereerd), processing, completed, failed. Taakitems kunnen ook title, duration en een al geregistreerde audio_url bevatten; wat ontbreekt, is simpelweg nog niet gegenereerd.

Zodra u de echte song_id hebt, gaat u verder met de API voor nummeropvraging of de download-endpoints.

Python-voorbeeld

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": "een vrolijk popnummer", "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

Compatibiliteit en opmerkingen

• Zonder accept_mode is het gedrag precies als voorheen: synchroon wachten, antwoord 200 en een array van nummers. Bestaande integraties hoeven niets aan te passen.
• Deze schakelaar werkt momenteel alleen op POST /api/music/create en POST /api/music/create/custom; de andere generatie-endpoints ondersteunen hem nog niet.
• Stuur ook een Idempotency-Key mee (uw eigen unieke tekenreeks, ≤128 tekens): dezelfde sleutel wordt maar één keer geaccepteerd, een herhaling geeft hetzelfde bewijs en er wordt niets dubbel gefactureerd. In asynchrone modus is dat extra belangrijk.
• Met accept_mode=async wordt wait_completion genegeerd (het bewijs komt direct terug, zonder op de nummers te wachten).
• Het bedrag wordt nog steeds vooraf afgeschreven bij acceptatie; een mislukte generatie wordt automatisch volledig terugbetaald.
• Limiet van het tekstveld: description bevat maximaal 3000 tekens (geteld in Unicode-tekens, een Han-teken telt als 1). Langere tekst geeft direct HTTP 400, komt niet in de generatie en wordt niet gefactureerd; de foutmelding noemt de gemeten lengte, bijvoorbeeld description must not exceed 3000 characters; received 4120. Dit endpoint heeft geen tekst-/stijlvelden; zie daarvoor "Limiet van het tekstveld" in de Generatie-API in aangepaste modus. De algemene regels staan in "Limieten van tekstvelden" van het Overzicht van de nieuwe API.
• Zonder references zijn gedrag, prijs en antwoord precies als voorheen: bestaande integraties hoeven niets aan te passen.
• Als referentiemateriaal wordt meegegeven (vooral meerdere nummers), gebruik dan liever de bewijsmodus accept_mode=async dan lang synchroon wachten; hoe lang de voorbereiding duurt, hangt af van hoeveelheid en herkomst van het materiaal.

Volgende stappen

Zijn de nummers niet klaar wanneer het antwoord binnenkomt, haal dan het eindresultaat op met de API voor nummeropvraging.

Voorbeeld van Node/Electron-integratie

Als u standaardgeneratie in het Electron-hoofdproces, een Node.js-server of een desktopclient inbouwt, is dit de aanbevolen flow:

1. Roep POST /api/music/create aan om de generatietaak te maken.
2. Lees song_id of id uit het antwoord.
3. Roep elke 2 seconden POST /api/music/query aan om de status te controleren.
4. Beschouw de generatie als klaar zodra audio_url in het resultaat verschijnt.

Gebruik de oude paden POST /api/generate of GET /api/clip?id=... niet meer; die horen niet bij het momenteel aanbevolen publieke integratieoppervlak.

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

Bewaar de API-sleutel in echte projecten in een server-omgevingsvariabele, een instelling van de desktopclient of een beveiligde opslag — nooit in front-endcode en nooit gecommit in een repository.