Overzicht van de Suno API-documentatie

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

Registreren met een e-mailadres is genoeg om een API-sleutel te maken. Een generatie kost ¥0,6 en levert 2 nummers op, met MP3/WAV-download, covers, Extend, stemmenscheiding en stemklonen. Basis-URL: https://www.suno-api.io.

Deze pagina beschrijft de beschikbare modellen, alle generatie- en bewerkingsendpoints, de facturering en de aanbevolen leesvolgorde. Lees hem bij een eerste integratie van boven naar beneden; de aanknopingspunten voor 401/403/429 staan hier ook.

Korte antwoorden

Hoe krijg ik een API-sleutel? Registreer met een e-mailadres, open de console, ga naar tokenbeheer en maak een token aan. Telefoonnummer en creditcard zijn niet nodig.

Wat kost een aanroep? Een generatie kost ¥0,6 en levert 2 nummers op. Statusopvragingen, WAV, songteksten met tijdstempels en promptsuggesties zijn gratis.

Welke modellen worden ondersteund? suno-v6 (standaard), suno-v6-wild en suno-v6-mini. De standaard generatiemodellen v5.5 en ouder zijn uitgefaseerd; bestaand werk blijft werken.

Wat is de basis-URL? https://www.suno-api.io, met de header Authorization: Bearer YOUR_API_KEY.

Momenteel beschikbare modellen

Voor normale songgeneratie kan de klant alleen suno-v6, suno-v6-wild en suno-v6-mini opgeven. Laat u model weg, dan wordt suno-v6 gebruikt.

De standaardmodellen suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 en suno-v5-5 zijn uitgefaseerd. In historische taken kunnen die namen nog staan, maar dat zijn historische gegevens en geen bewijs dat het model voor nieuwe aanvragen werkt. Stemmenscheiding is de uitzondering — zie Stems (scheiding van zang/begeleiding).

Authenticatie

Alle publieke API-sleutelendpoints gebruiken dezelfde headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Basis-URL:

https://www.suno-api.io

Algemene parameterafspraken

• Een number in de request body moet een JSON-getal zijn, nooit een percentage als tekst. Een intensiteit van 50% schrijft u als 0.5, nooit als 50 of 50%.
• Een boolean moet true of false zijn. Stuur geen true, false, 0 of 1 als vervanging.
• Velden met "nee" mogen helemaal wegblijven. Twijfelt u over een parameter, laat hem dan weg en laat de dienst zijn standaardgedrag gebruiken; stuur geen lege string, null of 0 in plaats van "niet verzonden", want 0 is bij sommige numerieke velden een geldige waarde.
• Veldnamen zijn spellinggevoelig. Elke endpointpagina noemt het aanbevolen veld en de compatibele aliassen; stuur ze precies zoals in de tabel. Waar de documentatie zegt dat snake_case en camelCase beide mogen, stuurt u niet beide tegelijk.
• Alle duurvelden die eindigen op _s of Seconds zijn in seconden en accepteren decimalen. Unix-tijdstempels worden apart beschreven, inclusief seconden of milliseconden.
• Een ID die begint met pending: is een plaatsaanduiding van het platform, geen echte song-ID. Gebruik die alleen waar het endpoint dat expliciet documenteert; wacht anders op de echte song_id.

Limieten voor tekstvelden

Overschrijding levert direct HTTP 400: er wordt niets gegenereerd, niets vooraf afgeschreven en er komt geen taakrecord. Geteld wordt in Unicode-tekens (één schriftteken telt als 1) en spaties aan begin en eind tellen mee.

Het foutbericht (message) noemt het veld en de gemeten lengte; met die twee getallen kunt u de tekst direct inkorten:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Geldt voor: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Eén uitzondering: description bij POST /api/music/sounds is beperkt tot 100 tekens, omdat het effectgeluid-pad de kortere limiet van het platform gebruikt.

Asynchrone generatie en audio-URL's

Endpoints voor muziekgeneratie werken standaard asynchroon. Als het eerste antwoord status gelijk heeft aan pending, submitted of processing, dan zijn lege audio_url, video_url of cover_url normaal en betekent dat geen mislukking. Bewaar de echte song_id (of de teruggegeven client_request_id) en poll het bijbehorende endpoint; lees en download een audio-URL pas als de status voltooid is.

⚠️ Audio-URL's verlopen na 7 dagen — verplaats uw bestanden op tijd

audio_url, wav_url, video_url en de URL's van de download-endpoints komen uit de objectopslag van het platform en verlopen standaard na 7 dagen (bestanden worden opgeruimd; een oude URL geeft 404 / downloadt niet).

• Verplaats de bestanden binnen die 7 dagen naar uw eigen opslag (eigen objectopslag, CDN of serverdisk). Behandel onze URL's niet als langdurige links.
• Een verlopen URL vraagt niet om opnieuw genereren en kost niets extra: roep de songquery-API (of de mediadownload-API) opnieuw aan voor een nieuwe geldige URL.

Wachttijden en timeout-instellingen

Generatie-endpoints zijn synchroon: de order wordt pas geaccepteerd en aan het platform doorgegeven wanneer het antwoord binnenkomt. Daarvoor moet de dienst een account inplannen en de nodige veiligheidscontrole doorstaan, zonder tussentijds antwoord — geen enkel ander endpoint ziet de order. Het enige betrouwbare bewijs dat "er iets is gegenereerd" is dus het antwoord zelf, niet wat u tijdens het wachten waarneemt.

Gemeten wachttijden (productie, familie /api/music/create, 18–20 september 2026)

• Ongeveer 10% van de aanvragen duurt langer dan 30 seconden en ongeveer 1% duurt 1–2 minuten. Een trage aanvraag betekent meestal dat er eerst een veiligheidscontrole nodig was.
• Velden, antwoordvorm, foutcodes en facturering zijn onveranderd, dus bestaande integraties hoeven alleen de client-timeout te verhogen — geen andere codewijziging.

Eisen aan de integratie

1. Zet de client-timeout op 300 seconden of meer. Clients met 30, 60 of 120 seconden verbreken de verbinding tijdens het wachten.
2. Geen antwoord betekent niet dat er niets is gegenereerd. Bij een timeout of weggevallen verbinding kan de order al geaccepteerd zijn en gegenereerd worden.
3. Probeer niet direct opnieuw na een timeout: een dubbele inzending maakt een tweede order en rekent opnieuw af.
4. Is de verbinding weggevallen, list dan iets later uw nummers met GET /api/music/songs (nieuwste eerst) — geaccepteerde orders verschijnen normaal. Verzend pas opnieuw als u heeft bevestigd dat de order echt ontbreekt.
5. Vermeld bij een storing de response-header X-Oneapi-Request-Id, zodat precies die aanvraag te vinden is.

Liever geen lange verbinding? Gebruik de ontvangstbevestiging-modus. POST /api/music/create en POST /api/music/create/custom ondersteunen een optionele ontvangstbevestiging: zet "accept_mode": "async" in de body (of de header X-Accept-Mode: async) en het endpoint geeft direct 202 met een bevestigingsnummer terug, terwijl de generatie op de achtergrond doorgaat; volg de voortgang met GET /api/music/requests/{request_id}. Een client met maar enkele tientallen seconden timeout kan "geen antwoord" dan niet meer verwarren met "niets gegenereerd" en ook niet dubbel afrekenen door herhalingen. Zie "Ontvangstbevestiging-modus" in de API voor genereren in eenvoudige modus.

Ter referentie: python requests gebruikt timeout=300, urllib gebruikt urlopen(..., timeout=300), Node gebruikt req.setTimeout(300000), curl gebruikt --max-time 300.

Aanbevolen endpointlijst

De endpoints /api/voice/clone/* en /api/music/generate-with-voice horen bij de vroege stemkloon-keten en worden niet aanbevolen voor nieuwe integraties; gebruik in plaats daarvan de 【Aanbevolen】 stemprofiel-API.

Geavanceerde parameters: Max Mode en Variety

Generatie-endpoints ondersteunen deze twee optionele parameters (weglaten behoudt gedrag en prijs):

Ondersteund door: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• Het dubbele tarief in de praktijk: een endpoint van ¥0,6 per aanroep wordt ¥1,2 met max_mode; genereren met een gekozen stem kost ¥1,2 per aanroep en ¥2,4 met Max Mode; de stemcover van de 【Aanbevolen】 stemprofiel-API kost ook ¥1,2 per aanroep (¥2,4 met max_mode).
• variety geldt alleen voor de suno-v6-familie (suno-v6, suno-v6-wild, suno-v6-mini); bij andere modellen geeft verzenden 400.
• Geluidseffecten, stems, concat, WAV en de Studio-bewerkingen (bijsnijden, sectie verwijderen, fade, achterstevoren, snelheid enzovoort) kennen deze parameters niet — expliciet verzenden geeft 400, zodat een parameter nooit stil wordt genegeerd.
• variety is het gehele getal 0-4; style_weight en weirdness_constraint zijn decimalen van 0 tot 1, dus de schalen verschillen.

Gemeenschappelijke antwoordvelden van nummers

Generatie-, cover-, extend-, scheidings- en query-endpoints geven meestal een array van nummers terug met deze velden:

Vier stappen om te integreren (minimaal voorbeeld)

Met deze vier stappen heeft u uw eerste nummer; de volledige velden per stap staan op de bijbehorende pagina van de aanbevolen endpointlijst.

# 1) Generatie insturen: ¥0,6, levert 2 nummers
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Dutch pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Pollen tot status completed is (3-5 seconden is een goed interval)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "de song_id uit stap 1"}'

# 3) Een media-URL ophalen: lees-endpoints zijn gratis; song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "dezelfde song_id", "kind": "song"}'

Als er iets misgaat: 401 / 402 / 403 / 429 in de foutengids; timeouts en dubbele afrekeningen in de sectie hierboven; details per endpoint in de lijst hieronder.

Aanbevelingen

• Nieuwe integraties gebruiken het beste overal suno-v6.
• Bij endpoints met een standaardprijs volgt het werkelijke bedrag de actuele prijsinstelling in de backoffice en het gevraagde model.
• Generatie-endpoints geven eerst een taak terug; haal de uiteindelijke audio op via /api/music/query.
• wait_completion=true blokkeert tot het einde en is geschikt voor tests met weinig volume; in productie is asynchroon pollen beter.
• Generatie-endpoints kunnen lang duren — zet de client-timeout op 300 seconden of meer en onthoud dat "geen antwoord" niet hetzelfde is als "niets gegenereerd".
• Uploaden, coveren, vervangen en WAV hangen af van platformaccounts en rechten op de bronclip; lees bij fouten eerst message of error_message.

Over deze documentatie

Deze pagina is herschikt rond de mogelijkheden die de Create UI daadwerkelijk aanbiedt; nieuwe integraties lezen hem het beste eerst. De oudere API-documentatie blijft beschikbaar in de sectie "Oudere API-documentatie (compatibel)" voor wie de eerdere werkwijze wil houden.