API voor spraakgeneratie (Speech)

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

Beschrijving van het endpoint

Speech zet een toespraaktekst of een beschrijving van één regel om in "spraak/toespraak"-audio, eventueel met achtergrondmuziek. Het past bij toespraken, toasten, voice-over, inspreekteksten, audiocontent en vergelijkbare situaties.

Let op: dit endpoint maakt spraakaudio, geen gezongen nummer (geen melodie en geen gezongen stem). Heb je zang nodig, gebruik dan de generatie-API in eenvoudige modus of de generatie-API in aangepaste modus.

Endpoint: POST /api/music/speech

Facturering: Betaald, momenteel standaard 0,6 ¥ per aanroep. Elke aanroep levert meestal 2 audio's op; het werkelijk gefactureerde bedrag volgt de 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 antwoorden de meeste verzoeken binnen enkele seconden (1-10 s); maar zoals bij andere synchrone generatie-endpoints kan het in extreme gevallen langer duren. 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.

Inhoudelijke naleving: het platform controleert de tekst op auteursrecht en contentbeleid. Wordt die beoordeeld als beschermd materiaal (bijvoorbeeld andermans songtekst of de letterlijke tekst van een bekend werk citeren), dan mislukt deze aanroep en wordt het hele bedrag automatisch terugbetaald. Stap over op je eigen formulering, of zet het citaat om in een parafrase, en probeer opnieuw.

Verzoekparameters

Headers

Body-parameters

Dit endpoint ondersteunt geen duration: meesturen geeft HTTP 400, het wordt niet stil genegeerd. De lengte van de toespraak wordt bepaald door de lengte van de inhoud van script.

Voorbeeldverzoeken

Minimaal verzoek (alleen de tekst)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Goedemorgen allemaal! Mijn toespraak vandaag gaat over onze tijd goed benutten en vooruitgaan."
  }'

Volledig verzoek (met toon, geslacht en achtergrondmuziek uit)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Python-voorbeeld

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Goedemiddag, collega\'s. Ik rapporteer over de voortgang van deze week.',
        'tone': 'rustig en helder, vergaderverslag',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # meestal 2 items
for item in items:
    print(item['song_id'], item['status'])

Toelichting op de parameters

script (de toespraak, verplicht)

• Plak de inhoud die u wilt uitspreken; u kunt ook één beschrijving schrijven en het model de toespraak laten opstellen (bijvoorbeeld "een peptalk in de rust voor een team dat twintig punten achterstaat, van een zachte mompel tot een brul uit volle borst").
• Regeleindes, alinea's en toneelregels zoals [pauze] kunt u direct opschrijven; het model volgt ze zoveel mogelijk.
• De limiet is 3000 tekens (geteld in Unicode-tekens; een Chinese ideogram telt als 1); daarboven geeft het 400 en worden er geen kosten gerekend.

tone (toon en setting, optioneel)

Het beschrijft hoe er gesproken wordt, niet wat er gezegd wordt. Neem bij voorkeur vier soorten informatie op: toon, tempo/ritme, emotie en setting.

Energiek en krachtig, tempo van langzaam naar snel, duidelijke pauzes; schoolaula, voor alle leerlingen en docenten
Warm en zacht, rustig tempo; huwelijksreceptie
Rustig en ingetogen, gelijkmatig en helder; verslag aan de raad van bestuur

De limiet is 1000 tekens. Laat u het weg, dan leidt het model het af uit de inhoud van script.

gender / vocal_gender (geslacht van de spreker, optioneel)

• Stuur m of male voor een mannenstem, f of female voor een vrouwenstem; de server normaliseert ze naar m / f.
• Beide veldnamen werken; gebruik er één: gender is de aanbevolen vorm voor dit endpoint; gebruikt u al de aangepaste modus, dan kunt u vocal_gender blijven gebruiken.
• Weglaten betekent "willekeurig", en het model beslist.

backing_music (achtergrondmuziek, optioneel)

• Standaard true (met achtergrondmuziek), gelijk aan de webversie van Suno.
• false geeft een toespraak met alleen stem, handig als u later zelf muziek of inspraak wilt toevoegen.
• Moet een JSON-boolean true / false zijn; de strings "true" en "1" worden ook geaccepteerd, maar booleans zijn aanbevolen.

model (model, optioneel)

Alle drie de klantgerichte modellen zijn beschikbaar tegen dezelfde prijs (0,6 ¥ per aanroep). De toespraak wordt gegenereerd door de Suno v6-familie; zonder waarde wordt het behandeld als suno-v6. Tenzij u een duidelijke voorkeur hebt, is dit veld meestal niet nodig.

Parametervalidatie en tekstlimieten

De volgende gevallen geven HTTP 400, en ze worden allemaal vóór de afrekening geblokkeerd, dus er ontstaan geen kosten:

Limieten van tekstvelden

Te lange tekst geeft ook HTTP 400 en start geen generatie en houdt niets vooraf af. Er wordt geteld in Unicode-tekens (een Chinese ideogram telt als 1) en spaties aan het begin en eind tellen mee:

De fout ziet eruit als script must not exceed 3000 characters; received 4120: het eerste woord is het veld dat de limiet overschreed en het einde is het werkelijke aantal, dus bij een 400 kunt u met die twee getallen direct inkorten.

Antwoord

Het antwoord is een nummer-array precies zoals bij de andere generatie-endpoints (meestal 2 items); bewaar de song_id en gebruik de API voor nummeropvraging en geschiedenis om de eindstatus en het audioadres op te vragen:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Onze tijd goed benutten",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Mislukte generatie en terugbetalingen

Mislukt de generatie, dan wordt het bedrag van die aanroep automatisch volledig terugbetaald; contact opnemen met support is niet nodig. De reden staat in het antwoord of in het error_message van de API voor nummeropvraging en geschiedenis.

De meest voorkomende oorzaak is een beoordeling als beschermd materiaal, bijvoorbeeld:

Your lyrics contain copyrighted material. Please change it and try again.

Vervang in dat geval de tekst door uw eigen formulering (of zet het citaat om in een parafrase) en dien opnieuw in.

Veelgestelde vragen

V: Waarom is het resultaat "spraak" en geen zang? A: Dit is het toespraak-endpoint en de uitvoer is spraakaudio. Voor zang gebruikt u de generatie- of aangepaste-modus-endpoints.

V: Waarom komen er elke keer 2 items terug? A: Zoals bij de andere generatie-endpoints van het platform levert één generatie 2 kandidaten op; vraag ze apart op via song_id en houd degene die u bevalt.

V: Hoe stuur ik de lengte? A: Die volgt uit de lengte van script; dit endpoint accepteert geen duration-parameter.

V: Kan ik een stem opgeven (bijvoorbeeld mijn gekloonde stem)? A: De huidige versie ondersteunt dat niet. De toespraak gebruikt een vaste set spraakstemmen en gender kiest mannelijk of vrouwelijk; hebt u uw eigen stem nodig, gebruik dan de betreffende functie van de API voor het maken van een stemprofiel (aanbevolen).

V: Wat gebeurt er als ik tone niet meestuur? A: Het model leidt toon en ritme af uit de inhoud van script. Wilt u een stijl betrouwbaar reproduceren, schrijf dan toon, tempo en setting in tone.

Compatibele velden

Gebruik bij nieuwe integraties consequent snake_case. De overige velden (script, tone, song_title, backing_music) hebben geen camelCase-aliassen.

Volgende stappen

Zodra u de song_id hebt:

1. Gebruik de API voor nummeropvraging en geschiedenis om de generatiestatus en het audioadres op te vragen;
2. Download of beluister het resultaat daarna met de API voor het downloaden en beluisteren van nummer-media;
3. Voor bulkdownloads of het kopiëren naar uw eigen opslag, zie de endpoints van het downloadcentrum.