Veelgestelde vragen
Hoe krijg ik mijn API sleutel?
Registreer op /get-api-key/ via Google of e-mail. Na aanmelding zie je je sleutel, saldo en een curl-voorbeeld. Elke account heeft één actieve sleutel. Je kunt op elk moment een nieuwe sleutel genereren; de oude wordt dan direct ongeldig.
Welke taalcode gebruik ik voor Nederlands?
Gebruik de ISO-code 'nl'. Hoewel de API de taal soms automatisch detecteert, is het aanbevolen de 'language'-parameter expliciet in te stellen voor niet-Engelse Latijnse teksten om foutieve detectie te voorkomen. Nederlands is een van de 23 ondersteunde talen.
Hoe verwerk ik een response met base64 data?
De API retourneert audio direct in de response body. Als je de SDK gebruikt, wordt de audio vaak als base64 of buffer geleverd. Decodeer deze data naar een bestand zoals mp3, wav, opus, flac of pcm, afhankelijk van de 'response_format' die je hebt opgegeven.
Kan ik meerdere voice presets tegelijk gebruiken?
Nee, elke API-aanvraag accepteert één 'voice'-waarde uit de 8 beschikbare presets. Voor langere teksten splitst de client de tekst in delen van maximaal 4096 karakters en voegt de audiobestanden samen. Je kunt niet meerdere stemmen in één enkele aanvraag combineren.
Wat is het verschil in response size tussen MP3 en WAV?
MP3 is gecomprimeerd en heeft een kleinere bestandsgrootte, terwijl WAV ruwe PCM-data bevat en aanzienlijk groter is. Beide formaten zijn beschikbaar via de 'response_format'-parameter. De keuze hangt af van je opslagbehoefte en verwerkingscapaciteit; de API levert beide direct.
Hoe weet ik welke voice welke taal spreekt?
Alle 8 stemmen (zoals Aria, Nova, Felix) kunnen elke van de 23 ondersteunde talen spreken. De stemkeuze bepaalt de timbre, niet de taal. Specificeer de gewenste taal via de 'language'-parameter of laat deze raden op basis van de tekstscriptie.
Wat gebeurt er bij een timeout?
Als de synthese mislukt, wordt het volledige bedrag terugboekt op je saldo. Mislukte aanvragen zijn dus gratis. Bij wachtrijden onder belasting kan de generatie langer duren, maar er wordt geen geld in rekening gebracht zolang de aanvraag niet succesvol is afgerond.
Is de API geschikt voor real-time streaming?
Nee, de API ondersteunt geen streaming, WebSocket of real-time gedeeltelijke audio. Je stuurt tekst en ontvangt het volledige audiobestand na verwerking. Voor real-time gebruik moet je de volledige respons afwachten voordat je de audio af speelt.
Hoe kan ik de snelheid van de speech aanpassen?
Gebruik de 'speed'-parameter in je JSON-body. De waarde moet tussen 0.25 en 4.0 liggen. Dit stelt je in staat de uitspraaktempo te vertragen of versnellen zonder de kwaliteit van de synthese significant te beïnvloeden binnen deze marges.
Moet ik de language parameter altijd instellen?
Niet altijd, maar wel aanbevolen voor niet-Engelse teksten in Latijns schrift. De API probeert de taal te raden, maar dit kan fout gaan. Voor andere scripts wordt de taal vaak correct gedetecteerd. Voor nauwkeurigheid stel je 'language' expliciet in.
Wordt er een content-type header verwacht?
Ja, je moet een POST-request sturen met 'Content-Type: application/json'. De body moet een JSON-object bevatten met de velden 'model', 'input', 'voice' en optioneel 'response_format', 'speed' en 'language'. Zonder correcte header wordt de request niet verwerkt.
Hoe lang blijft de API sleutel geldig?
De API-sleutel blijft geldig tot je een nieuwe genereert. Je kunt op elk moment een nieuwe sleutel aanvragen; de oude wordt dan onmiddellijk ongeldig. Er is geen vaste verloopdatum voor de sleutel zelf, alleen je saldo kan opraakken.
Kan ik de API gebruiken in een serverless omgeving?
Ja, de API is een standaard HTTP-endpoint dat goed werkt in serverless omgevingen. Je stuurt een JSON-request en ontvangt een audiobestand. Houd rekening met de rate limits van 60 requests per minuut per sleutel en de laadtijden bij wachtrijen.
Hoeveel geheugen verbruikt de API client?
Het geheugenverbruik hangt af van je implementatie en de grootte van het audiobestand. De API zelf verbruikt geen client-geheugen. Houd er rekening mee dat WAV-bestanden groter zijn dan MP3, wat meer geheugen en opslagruimte vereist bij verwerking.
Eerste verzoek
curl
curl https://api.kb333.info/v1/audio/speech \
-H "Authorization: Bearer $TTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
--output hello.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.kb333.info/v1", api_key="tts-...")
with client.audio.speech.with_streaming_response.create(
model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
response.stream_to_file("hello.mp3")Node.js (openai)
import OpenAI from "openai";
import fs from "node:fs";
const client = new OpenAI({ baseURL: "https://api.kb333.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));| voice | |
|---|---|
aria | vrouwelijk |
nova | vrouwelijk |
luna | vrouwelijk |
sage | vrouwelijk |
felix | mannelijk |
milo | mannelijk |
atlas | mannelijk |
orion | mannelijk |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Authenticatie
Authenticatie verloopt via een unieke API-sleutel die je genereert in het dashboard op /get-api-key/. Elke account heeft één actieve sleutel. Bij registratie via Google of e-mail ontvang je toegang tot je account en API-sleutel.
De sleutel wordt meegegeven in de request headers. Zorg ervoor dat je de juiste prefix gebruikt om fouten bij authenticatie te voorkomen tijdens de integratie.
API sleutel genereren in dashboard
Ga naar de /get-api-key/ pagina van je account. Hier zie je je huidige sleutel, saldo en verbruik. Je kunt een nieuwe sleutel genereren als de oude verloren is gegaan of als je zeker wilt weten dat hij niet meer gebruikt wordt door integraties.
- Sleutel begint met 'tts-' gevolgd door alfanumerieke tekens.
- Elk account heeft één actieve sleutel tegelijk.
- Nieuwe sleutels worden direct actief na generatie.
Authorization header: Bearer <key>
Voeg de header 'Authorization: Bearer tts-<jouwsleutel>' toe aan elke HTTP-request. Dit is de enige manier om je identiteit te verifiëren bij de API. Zonder deze header wordt je request geweigerd met een 401-foutcode.
- Gebruik geen query parameters voor de sleutel.
- Sla de sleutel veilig op in je omgevingvariabelen.
- Controleer de spelling van de header naam.
Regeneratie sleutel stopt oude direct
Wanneer je een nieuwe API-sleutel genereert, wordt de oude sleutel onmiddellijk ongeldig. Dit zorgt ervoor dat er geen onbeheste toegang meer is via de oude sleutel. Dit is ideaal voor veiligheidsdoeleinden als je vermoedt dat je sleutel gelekt is.
- Oude sleutel stopt direct na regeneratie.
- Controleer je integraties na regeneratie.
- Geen wachttijd bij overschakelen.
Eerste request met cURL
Stuur een POST-request naar https://api.kb333.info/v1/audio/speech met een JSON body. Deze endpoint accepteert tekst en converteert deze naar audio in de opgegeven formaten. Zorg dat de Authorization header correct is ingesteld met je Bearer token.
POST endpoint URL specificeren
De API vereist een POST-verzoek naar het speech-endpoint. Voeg de header Authorization: Bearer <jouw-sleutel> toe voor authenticatie. Zonder geldige sleutel ontvang je een 401-fout.
JSON body structuur: model, input, voice
De request body moet minstens de velden model, input en voice bevatten. model is altijd tts-1 of tts-1-hd. input bevat de tekst (maximaal 4096 tekens), en voice is een van de acht beschikbare stemmen. Optioneel kun je response_format en speed specificeren.
- Voorbeeld cURL: curl -X POST https://api.kb333.info/v1/audio/speech -H "Authorization: Bearer tts-..." -H "Content-Type: application/json" -d '{"model": "tts-1", "input": "Hallo wereld", "voice": "nova"}'
Response verwerken en audio opslaan
Bij een succesvol verzoek (200 OK) ontvang je de audio als binary data in het geselecteerde formaat. Verwerk de binary data direct of sla het bestand op. Foutcodes zoals 429 (rate limit) of 500 (interne fout) worden als JSON retourneerd met een foutmelding.
Integratie met OpenAI SDK
De officiële OpenAI SDKs werken direct met SpraakZaak door de base_url aan te passen naar https://api.kb333.info/v1. Je gebruikt dezelfde requeststructuur als het speech-endpoint, waardoor je bestaande code minimal moet aanpassen.
Dit vereist geen eigen library. Je kunt de standaard Python- of JavaScript-clienten gebruiken door de API-key te wijzigen en de basis-URL te specificeren in de clientconfiguratie.
base_url wijzigen naar api.kb333.info/v1
Vervang de standaard API-base-URL in je SDK-configuratie door https://api.kb333.info/v1. Dit zorgt ervoor dat verzoeken correct worden doorgestuurd naar onze infrastructuur.
Je hebt geen extra middleware nodig; de SDK communiceert direct met de endpoint POST /v1/audio/speech.
- Stel de base_url in op https://api.kb333.info/v1
- Gebruik je bestaande SpraakZaak API-key in de Authorization header
Gebruik van officiële Python/JS libraries
De SDKs van OpenAI werken met onze API door de base_url aan te passen. Je importeert de library zoals gebruikelijk en configureert de client met onze basis-URL.
De logica voor het verzenden van tekst en het ontvangen van audio blijft identiek aan de standaardimplementatie.
- Python: openai.OpenAI(base_url="https://api.kb333.info/v1", api_key="tts-...")
- JavaScript: new OpenAI({ baseURL: 'https://api.kb333.info/v1', apiKey: 'tts-...' })
Compatibiliteit met standaard endpoints
Alle standaard parameters zoals model, input, voice en response_format worden ondersteund. De respons structuur is gelijk aan de OpenAI API.
Dit maakt migratie of parallel gebruik eenvoudig zonder extra transformatielagen voor de payload.
Beschikbare modellen
De API ondersteunt twee modellen, tts-1 en tts-1-hd. Beide gebruiken dezelfde synthese-engine en hebben een identieke prijsstelling van $10 per miljoen tekens. Het keuzeverschil ligt uitsluitend in de audiokwaliteit, niet in de kosten of de structuur van de request.
Voor de meeste localisatie- en bulkverwerkingswerkflows is het standaard model voldoende. Het HD-model biedt een hogere resolutie en is geschikt wanneer audiokwaliteit voorop staat.
tts-1: Standaard prijs en kwaliteit
Dit model levert snelle en duidelijke spraakoutput. Het is geoptimaliseerd voor hoge doorvoercapaciteit en werkt uitstekend voor tekst die snel moet worden geconverteerd, zoals nieuwsberichten of korte uitlegteksten. De geluidskwaliteit is consistent en geschikt voor de meeste commerciële toepassingen.
tts-1-hd: Hogere kwaliteit, zelfde prijs
Het HD-model produceert audio met een hogere detailgraad en natuurlijkere klank. Omdat de prijs per karakter exact hetzelfde is als bij het standaardmodel, levert dit geen extra kosten op voor uw project. Het is de ideale keuze voor lange narraties of content waar audiokwaliteit cruciaal is.
U betaalt nooit meer voor HD-audio. De prijs blijft vast op $0,01 per 1.000 tekens, ongeacht welk model u selecteert.
Selectie van model in request body
U specificeert het gewenste model in de JSON-body van uw POST-request naar /v1/audio/speech. De parameter heet 'model' en accepteert de waarden 'tts-1' of 'tts-1-hd'. Deze keuze is per request los te stellen, waardoor u binnen één workflow beide kwaliteiten kunt gebruiken.
Voorbeeld van de structuur voor de standaardversie:
- "model": "tts-1"
- "model": "tts-1-hd"
Vereisten voor input
Je kunt maximaal 4096 tekens per API-request versturen. Spaces en leestekens tellen mee in deze limiet. Voor langere teksten split je de input op en voeg je de audiobestanden achteraf samen.
De input tekst moet een UTF-8 string zijn. Dit is de standaard voor moderne API-integraties en wordt door alle SDK's correct afgehandeld.
Maximaal 4096 tekens per request
Elke request mag niet meer dan 4096 tekens bevatten. Houd rekening met spaties en leestekens als je de limiet berekent. Bij langere teksten deel je de input op in meerdere requests en combineer je de resulterende audiobestanden.
Tekst coderen als UTF-8 string
De API verwacht de input tekst als een geldige UTF-8 string. Dit ondersteunt alle 23 beschikbare talen.
Optionele language parameter instellen
De API probeert de taal automatisch te raden op basis van het script. Latijnse tekst wordt standaard als Engels geïnterpreteerd. Voor andere talen met Latijns schrift, zoals Nederlands of Frans, stel je de language parameter expliciet in om uitsprakenfouten te voorkomen.
- Standaard: Engels bij Latijns schrift
- Voorkeur: expliciete ISO code instellen
- Ondersteunde talen: 23 opties

Output formaten
Kies het juiste formaat op basis van je verwerkingspipeline. De API retourneert het audiobestand direct in de response body.
Het formaat wordt bepaald door de response_format parameter in je request. Alle formaten worden ondersteund voor elke voice en taal, zonder extra kosten voor het kiezen van een specifiek codec.
MP3: Compacte grootte, breed supported
MP3 is de standaardkeuze voor de meeste integraties. Het formaat biedt een goede balans tussen geluidskwaliteit en bestandsgrootte, waardoor het ideaal is voor webimplementaties en snelle verwerking van bulkteksten.
De meeste mediaplayers en streamingdiensten ondersteunen MP3 out-of-the-box. Dit maakt het het veiligste startpunt voor localisatiebureaus die audio snel willen integreren in hun workflows.
- Geschikt voor web en mobiele apps
- Automatische compressie door de API
WAV: Verliesvrij, grote bestandsgrootte
WAV levert ongecomprimeerde audio in PCM-formaat. Dit formaat is ideaal voor post-productie, waarbij je de audio verder wilt bewerken in DAW-software zonder verdere compressie-artefacten.
Let op de grotere bestandsgrootten: WAV-bestanden zijn aanzienlijk groter dan MP3's van dezelfde duur. Dit kan relevant zijn bij hoge volumes tekst of beperkte bandbreedte.
- Ongecomprimeerde 16-bit audio
- Ideaal voor verdere post-productie
Opus/FLAC/PCM: Voor gespecialiseerd gebruik
Opus biedt efficiënte compressie met uitstekende kwaliteit, geschikt voor moderne streamingprotocollen. FLAC levert verliesvrije compressie, handig voor archiefdoeleinden zonder kwaliteitsverlies.
PCM retourneert raw audio data, wat nuttig is voor directe verwerking in gespecialiseerde software die eigen codec-implementaties gebruikt. Deze formaten vereisen mogelijk extra handling in je code.
- Opus: efficiënte compressie
- FLAC: verliesvrij archief
- PCM: raw data voor custom pipelines
Foutcodes en afhandeling
De API retourteert specifieke HTTP-statuscodes om fouten in authenticatie, limieten of synthese aan te duiden. Deze codes stellen je in staat om fouten direct af te handelen in je integratielogica, zonder dat er extra metadata nodig is.
Voor veelvoorkomende situaties zoals een ongeldige sleutel of overschreden rate limit, is de foutmelding expliciet. Dit voorkomt onnodige wachttijden en zorgt voor betrouwbare verwerking bij bulkrequests.
401: Ongeldige API sleutel
Een 401-fout treedt op wanneer de Authorization-header ontbreekt, verkeerd gevormd is of een niet-bestende sleutel bevat. Controleer of de sleutel begint met tts- en of deze actief is op je account.
Het regenereren van een sleutel maakt de vorige direct ongeldig. Zorg dat je integratie de nieuwe sleutel onmiddellijk overneemt om onderbrekingen in de dienstverlening te voorkomen.
- Controleer de header:
Authorization: Bearer tts-... - Verifieer of de sleutel niet verlopen is
- Regeneratie invalideren directe oude sleutel
429: Rate limit overschreden
Je hebt de limiet van 60 requests per minuut overschreden (of 10 voor nieuwe accounts). De API accepteert geen nieuwe verzoeken totdat de limiet weer beschikbaar is.
Overschrijdingen leiden tot wachtrijverwerking. Implementeer backoff-strategieën om herhaalde pogingen bij een 429-fout te beheersen.
- Limiet: 60 req/min (na top-up)
- Limiet: 10 req/min (nieuw account)
- Gebruik backoff bij 429
500: Interne server fout bij synthese
Een 500-fout betekent dat de synthese is mislukt tijdens het verwerkingsproces. Dit kan komen door tijdelijke serverbelasting of onverwachte fouten in de engine.
Deze requests worden niet in rekening gebracht. Probeer het verzoek opnieuw met dezelfde parameters; de kosten blijven gelijk als de fout optreedt.
- Synthese mislukt tijdens processing
- Geen kosten voor gefaalde requests
- Probeer opnieuw met zelfde parameters
Rate limits en limieten
SpraakZaak hanteert duidelijke limieten voor API-aanroepen om de stabiliteit van de synthesepool te gareren. Deze limieten zijn gebonden aan je API-sleutel en verschillen afhankelijk van de status van je account.
Bij overschrijding worden aanvragen niet onmiddellijk afgewezen, maar in een wachtrij geplaatst. Dit zorgt ervoor dat je batchverwerking niet abrupt stopt, maar wel vertraagt naarmate de wachttijd toeneemt.
60 requests per minuut na top-up
Zodra je account is opgewaardeerd met een top-up (minimaal $5), heb je toegang tot 60 verzoeken per minuut. Dit is de standaard capaciteit voor productionele workflows en bulkverwerking van lokale tekst-naar-spraakprojecten.
10 requests per minuut voor nieuwe accounts
Nieuwe accounts, zoals die na registratie via Google of e-mail, starten met een limiet van 10 requests per minuut. Deze beperking geldt totdat er een eerste top-up is uitgevoerd, waardoor de limiet direct omhoog gaat naar 60.
Wachtrij verwerking bij overschrijding
Als je de limiet bereikt, worden aanvragen in een wachtrij geplaatst en één voor één verwerkt. Omdat synthese ongeveer realtime verloopt (25 tekens per seconde), kunnen lange teksten langzaam door de wachtrij stromen. Je hoeft geen backoff-strategie te implementeren; de API handhaaft de volgorde zelf.
Luister naar de 8 stemmen
Elk voorbeeld hieronder is gegenereerd door deze API met dezelfde zin. Verifieer of de gegenereerde audio de beoogde taal correct weergeeft, vooral wanneer de automatische taalherkenning niet exact was.
23 talen
Elke stem kan elke van deze talen spreken.
