Generatie-API in aangepaste modus

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

Beschrijving van het endpoint

De aangepaste modus past wanneer tekst, stijl en titel al klaar zijn en u de zingende stem, de sterkte van de stijlinvloed en de mate van willekeur van de generatie wilt sturen.

Endpoint: POST /api/music/create/custom

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.

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

Toelichting op de geavanceerde parameters

Geslacht van de stem vocal_gender

• Stuur m of male voor een mannenstem, f of female voor een vrouwenstem.
• De dienst normaliseert male en female naar respectievelijk m en f.
• Met instrumental=true wordt er geen parameter voor stemgeslacht naar de generatiedienst gestuurd.

Stijlinvloed style_weight

Stuurt hoe sterk het resultaat style_tags volgt. Hoe hoger de waarde, hoe meer het resultaat de opgegeven stiltags volgt.

Willekeur weirdness_constraint

Stuurt hoeveel het resultaat varieert en experimenteert. Hogere waarden geven meestal meer variatie; lagere waarden een veiliger resultaat.

Beide numerieke parameters lopen van 0.0 tot 1.0, en 0 is een geldige expliciete waarde. Alleen het veld helemaal weglaten betekent "niet opgegeven".

Let bij het invullen op dat het decimale breuken zijn, geen procentuele gehele getallen. Richtlijn: 0.0 tot 0.3 is conservatief, 0.4 tot 0.6 is gebalanceerd, 0.7 tot 1.0 is experimenteler; zonder duidelijke voorkeur gebruikt u 0.5 of laat u ze gewoon weg. Voorbeeld: weirdness_constraint: 0.5, nooit 50 of 50%.

Met instrumental=true ontstaat een instrumentaal nummer, dus tekst en stemgeslacht werken niet zoals bij een gezongen nummer; hebt u zang nodig, stuur dan false of laat het veld weg. Booleaanse velden moeten JSON-true/false gebruiken, geen tekenreeksen.

Python-voorbeeldverzoek

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nDe nacht valt over de zee\neen avondbries glijdt langs het raam',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Avondbries aan zee',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Ontvangstbewijsmodus (optioneel)

Dit endpoint ondersteunt ook de ontvangstbewijsmodus van de Generatie-API in eenvoudige modus: met "accept_mode": "async" in de body (of de header X-Accept-Mode: async) antwoordt het endpoint direct met 202 en een bewijsnummer, loopt de generatie op de achtergrond door, en volgt u de voortgang met GET /api/music/requests/{request_id}.

Geschikt voor clients die geen lange verbindingen mogen houden, of die niet willen dat een timeout wordt gelezen als "er is niets gegenereerd". Zonder die parameter is het gedrag precies als voorheen.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Avondbries aan zee",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

De vorm van het antwoord en de manier van pollen staan in de sectie "Ontvangstbewijsmodus" van de Generatie-API in eenvoudige modus.

Parametervalidatie

Deze gevallen geven HTTP 400, en het message van de fout noemt het ongeldige veld:

• style_weight of weirdness_constraint is geen getal.
• Een numerieke waarde ligt onder 0.0 of boven 1.0.
• vocal_gender is niet een van m, f, male, female.

Limieten van tekstvelden

Deze velden geven bij overschrijding ook HTTP 400, komen nooit in de generatie en worden niet vooraf afgeschreven. Er wordt geteld in Unicode-tekens (een Han-teken telt als 1) en spaties aan het begin en eind tellen mee:

De foutmelding ziet er zo uit: style_tags must not exceed 1000 characters; received 2772. Het eerste woord is het veld dat is overschreden en aan het eind staat het gemeten aantal, dus bij een 400 knipt u met die twee getallen in plaats van veld voor veld te proberen. De algemene regels staan in "Limieten van tekstvelden" van het Overzicht van de nieuwe API.

Antwoord

Het endpoint geeft meestal een array met 2 nummers terug. Een asynchrone aanvraag start normaal in pending; bewaar de song_id en lees de eindstatus en het audioadres via de API voor nummeropvraging. De nummervelden zijn dezelfde als in de Generatie-API in eenvoudige modus.

Compatibele velden

Nieuwe integraties gebruiken overal snake_case. Draagt één aanvraag zowel snake_case als camelCase, dan wint de snake_case-waarde.