Veelgestelde vragen
Welke SDK is het beste voor Python gebruikers?
Gebruik de OpenAI SDK voor Python. Pas de base_url aan naar https://api.kb333.info/v1 en voeg je API-sleutel toe als Bearer token. Dit werkt direct met de standaard verzoeken voor speech generatie, zonder dat je een specifieke SDK van SpraakZaak hoeft te installeren of te configureren.
Hoe split ik een tekst van 10.000 tekens optimaal?
De API accepteert maximaal 4096 tekens per verzoek. Split je tekst in delen van deze lengte en stuur elk deel afzonderlijk. Verzamel de gegenereerde audiofragmenten en voeg ze samen tot één bestand. Dit zorgt voor betrouwbare verwerking van lange teksten zonder verlies van context of audio-integriteit.
Moet ik de language parameter altijd specificeren?
Niet altijd, maar wel aanbevolen voor niet-Engelse tekst in Latijns schrift. De API gis de taal op basis van het script, waarbij Latijns standaard Engels is. Specificeer de ISO-taalcode expliciet om foutieve gissingen te voorkomen, vooral bij talen zoals Nederlands, Duits of Frans die dezelfde schriften delen.
Wat is de beste manier om fouten te loggen?
Log de response statuscodes en foutmeldingen van de API. Omdat mislukte verzoeken volledig worden terugbetaald, is het belangrijk om te weten welke verzoeken faalden voor je facturatiecontrole. Houd ook de request-id en het tijdstip bij voor eventuele ondersteuning via e-mail bij twijfel over je saldo.
Hoeveel API sleutels heb ik nodig voor schaalbaarheid?
Je hebt één actieve sleutel per account. De limiet is 60 verzoeken per minuut. Als je meer capaciteit nodig hebt, kun je een nieuwe sleutel genereren die de oude onmiddellijk vervangt, maar dit vermindert de rate limit per sleutel niet; gebruik meerdere sleutels tegelijk voor hogere doorvoer. Dit is handig om de limieten te resetten of te isoleren voor verschillende projecten.
Kan ik de API gebruiken voor live presentaties?
Nee, de API is niet geschikt voor real-time streaming of lage latentie. Tekstverwerking duurt enkele seconden voor korte zinnen en is ongeveer real-time voor lange teksten. Omdat verzoeken in wachtrijen worden verwerkt, is er geen garantie voor directe audio-uitvoer, wat het ongeschikt maakt voor interactieve live situaties.
Hoe verwerk ik JSON response data efficiënt?
De API retourneert de audio direct in de response body. Parse de HTTP response niet als JSON maar als een bestand. Sla de audiobytes direct op of stream ze naar een bestandssysteem. Controleer de statuscode om te bevestigen dat de synthes succesvol was voordat je de data verwerkt.
Wat zijn de kosten voor een typisch audioboek?
De kosten bedragen $0,01 per 1000 tekens, inclusief spaties en leestekens. Een typisch audioboek van 80.000 tekens kost dus $0,80. Dit is gebaseerd op de standaard tarieven van $10 per miljoen tekens. De prijs is identiek voor zowel tts-1 als tts-1-hd modellen.
Is er een verschil in latency tussen modellen?
De verwerkingstijd hangt af van de tekstduur en wachtrijbelasting, niet van het model. Beide modellen, tts-1 en tts-1-hd, gebruiken dezelfde engine en hebben dezelfde prijs. De latentie wordt bepaald door de wachtrij voor synthes en de lengte van de tekst, niet door de keuze van het model.
Hoe zorg ik voor consistente audio kwaliteit?
Gebruik dezelfde voice en response_format voor vergelijkbare projecten. De kwaliteit is afhankelijk van de gekozen voice preset en het formaat (mp3, wav, opus, flac, pcm). Variatie in snelheid (0.25–4.0) kan de luisterervaring beïnvloeden, dus houd deze instellingen consistent voor uniforme output in je publicatieworkflow.
Kan ik de API integreren met Adobe Audition?
Ja, je kunt de gegenereerde audiobestanden importeren in Adobe Audition. Download de audio via de API en open het bestand in je DAW. De API ondersteunt formaten zoals wav en mp3, die breed compatibel zijn met professionele audio-software voor verdere bewerking, mixen en postproductie van je content.
Wat is de beste praktijk voor foutopsporing?
Controleer eerst de HTTP statuscode en de response body op foutmeldingen. Verifieer of je API-sleutel correct is geconfigureerd en of de tekst binnen de limiet van 4096 tekens valt. Controleer ook of de gekozen voice en taal geldig zijn. Mislukte verzoeken worden volledig terugbetaald, dus controleer je saldo.
Hoe monitor ik mijn verbruik in real-time?
Raadpleeg het dashboard op /get-api-key/ voor je saldo, verbruik en resterende tekens. De API zelf retourneert geen realtime verbruiksstatistieken in de response. Gebruik de weergave op de website om je uitgaven te volgen. Gegevens worden bijgehouden voor facturatie, maar gedetailleerde logs zijn beperkt tot de interface.
Zijn er beperkingen aan het aantal characters per jaar?
Nee, er zijn geen jaarlijkse limieten voor het aantal tekens. Je betaalt per gebruikt teken, met een tarief van $10 per miljoen tekens. Je saldo loopt niet leeg door een tijdsverloop en er zijn geen maandelijkse abonnementen of minimale bestedingen. Je kunt onbeperkt tekens genereren zolang er saldo is.
Voorbereiding van tekstinhoud
Voordat tekst naar audio wordt omgezet, is nauwkeurige karaktertelling essentieel voor de kostenraming. Elke spatie en leesteken telt mee. Bij een tarief van $0,01 per 1.000 tekens bepaalt de lengte direct de uitgave. Een nauwkeurige telling voorkomt verrassingen bij het verwerken van grote boekteksten of artikelen.
Tekens tellen voor kostenraming
Houd rekening met de totale lengte van uw manuscript. Omdat elke karakter wordt gefactureerd, kan een klein verschil in opmaak de kosten beïnvloeden. Gebruik uw API-sleutel om uw huidige saldo en verbruik te monitoren tijdens het verwerkingsproces.
- Elk teken, inclusief spaties, telt mee.
- Maximaal 4096 tekens per request.
- Kosten: $0,01 per 1.000 tekens.
Tekst opschonen voor synthese
Verwijder onnodige witregels en dubbele spaties voordat u de tekst naar de API stuurt. Dit vermindert het karaktergebruik zonder de betekenis te verstoren. Zorg dat de tekst enkel de te converteren inhoud bevat, zonder HTML-tags of metadata die de synthese kunnen verstoren.
Splitsen van lange paragrafen
De API accepteert maximaal 4096 tekens per request. Voor langere teksten moet u splitsen en de audiobestanden later samenvoegen. Dit zorgt voor een stabiele verwerking en voorkomt time-outs bij grote documenten. Zorg dat u de volgorde van de audiofragmenten behoudt voor de uiteindelijke output.
Keuze van API integratie methode
Kies je integratiemethode op basis van je technische stack en schaalbehoeften. Voor snelle validatie van tekstinvoer en stemkeuzes volstaat een direct cURL-commando. Voor productomgevingen met hoge betrouwbaarheidsvereisten raden we de officiële OpenAI SDK aan, aangezien deze de vereiste request-shape correct verwerkt bij wijziging van de base_url.
Direct cURL commando voor tests
Gebruik cURL voor directe verificatie van de API-endpoint zonder extra afhankelijkheden. Dit is ideaal voor het snel testen van tekstlengte en audioformaten.
- Post JSON naar https://api.kb333.info/v1/audio/speech
- Voeg header Authorization: Bearer tts-... toe
OpenAI SDK voor robuuste apps
De OpenAI SDKs werken direct door de base_url aan te passen naar https://api.kb333.info/v1. Dit minimaliseert fouten in de request-structuur en biedt directe compatibiliteit met bestaande codebases die de speech endpoint gebruiken.
- Instellen van base_url naar de API-domeinnaam
- Gebruik van standaard library foutafhandeling
Custom HTTP client voor specifieke behoeften
Voor projecten met strikte geheugenbeperkingen of unieke retry-logica kun je een custom HTTP client gebruiken. Zorg ervoor dat de JSON-body exact overeenkomt met de vereiste velden: model, input, voice en response_format.
Configuratie van parameters
De API vereist drie kernparameters om audio te genereren: de stem, het formaat en de snelheid. Deze instellingen bepalen direct de kwaliteit en de verwerkingstijd van de gegenereerde bestanden. Het is essentieel om deze variabelen nauwkeurig af te stemmen op de inhoud van het tekstbestand.
Instellen van voice preset
Kies uit acht presets die zijn gebaseerd op gelicentieerde opnames. De keuze hangt af van de toon van de publicatie: Aria voor heldere narratie, Luna voor verhalende stijl of Atlas voor neutrale nieuwsberichten. Elke stem ondersteunt alle 23 beschikbare talen, waaronder Nederlands.
- Aria (warm, duidelijk)
- Nova (helder, enthousiast)
- Atlas (neutraal, nieuws)
Kiezen van audio format
Selecteer het gewenste formaat via response_format: mp3, wav, opus, flac of pcm. Voor bulkverwerking en lage opslagkosten is mp3 of opus vaak het meest efficiënt. WAV en FLAC bieden hogere kwaliteit zonder compressieverlies, wat nuttig is voor post-productie.
Bepalen van snelheidsfactor
De speed parameter accepteert waarden tussen 0.25 en 4.0. Standaard is de snelheid 1.0, wat overeenkomt met natuurlijke spreektempo. Pas de snelheid aan voor audioboeken of snelle nieuwsupdates, maar vermijd extreme waarden die de verstaanbaarheid kunnen verminderen.
Verwerking van grote volumes
Voor bulkverwerking van honderden pagina’s is het essentieel om teksten te splitsen in segmenten van maximaal 4096 tekens. Elke split genereert een afzonderlijk audio bestand dat achteraf samen wordt gevoegd tot één coherent bestand. Dit voorkomt fouten bij grote input en houdt de verwerkingstabellen overzichtig.
Batch verwerking strategieën
Verwerk teksten sequentieel of in kleine batches om geheugenbelastingspieken te voorkomen. Omdat de API verzoeken één voor één verwerkt, kan onder hoge belasting wachttijd ontstaan. Plan je batchgroottes daarom realistisch in, afhankelijk van de verwachte generatiesnelheid van ongeveer 25 tekens per seconde.
- Maximaal 4096 tekens per verzoek.
- Voeg audio bestanden achteraf samen.
- Houd rekening met wachtrijtijd.
Handelen bij rate limits
Je account is beperkt tot zestig verzoeken per minuut per sleutel. Voor het eerst geldig worden is dit limiet verlaegd naar tien verzoeken per minuut tot na de eerste opwaardering. Overschrijdingen resulteren in foutmeldingen; implementeer backoff-strategieën in je client code om dit te hanteren.
- Maximaal 60 requests/minuut.
- 10 requests/minuut voor nieuwe accounts.
- Implementeer retry logic.
Gebruik van meerdere API sleutels
Bij zeer grote volumes kun je meerdere API sleutels tegelijkertijd gebruiken. Elke sleutel telt onafhankelijk mee voor de rate limit. Dit stelt je in staat de doorvoer te verdubbelen of verdrievoudigen door simpelweg een nieuwe sleutel aan te maken en deze naast de bestaande te gebruiken.
Validatie van output
Na het ontvangen van de audiorespons is directe validatie essentieel voor de integriteit van de publicatie. Controleer eerst of het bestand correct is gedownload en de verwachte grootte heeft, wat een indicatie is van een geslaagde synthese zonder corruptie.
Vervolgens verifieer je de taalaangifte en controleer je of het bestand het inaudibele watermerk bevat dat aangeeft dat het om synthetische spraak gaat. Deze stappen garanderen dat de output voldoet aan de technische eisen voor verdere distributie.
Controleren van bestandsgrootte
Controleer de bestandsgrootte van de ontvangen audio om te bevestigen dat de syntheseprocessus compleet was. Een plotselinge afwijking in de bestandsgrootte kan wijzen op een onderbroken verbinding of een corrupte respons, waardoor het bestand mogelijk niet afspeelbaar is in je downstream systemen.
Verifiëren van taalcorrectheid
Verifieer of de gegenereerde audio de beoogde taal correct weergeeft, vooral wanneer de automatische taalherkenning niet exact was. Controleer de uitspraak van eigennamen en vakterminologie binnen de context van de tekst. Dit voorkomt fouten bij de finalisatie van gelokaliseerde inhoud.
Luisteren naar watermerk
Elk gegenereerd bestand bevat een onhoorbaar watermerk dat de synthetische oorsprong aangeeft. Luister naar de audio en controleer eventuele metadata om te bevestigen dat het watermerk aanwezig is. Dit is belangrijk voor transparantie en rechtenbeheer bij de eindgebruiker van de content.
Foutopsporing en logging
Logging is essentieel voor het traceren van TTS-verzoeken in je publicatiepipeline. Omdat de API geen expliciete request ID headers retourneert, moet je de request metadata registreren, zoals de tijdstippen en statuscodes. Deze gegevens worden ook gebruikt voor facturering, wat de nauwkeurigheid van je logs waarborgt.
Registreren van request IDs
Log de tijdstippen, het aantal verwerkte karakters en de status van elk verzoek. Dit vormt de basis voor het achterhalen van verloren audiobestanden of dubbele factureringen zonder afhankelijk te zijn van externe ID-velden.
Analyseren van foutcodes
Interne fouten tijdens synthese worden volledig vergoed. Controleer of de fout optrad vóór de voltooiing van de syntheseprocessus. Bij een fout ontvang je een volledige terugbetaling; bij geslaagde verzoeken is het audiobestand direct beschikbaar in de response.
- Interne fouten = volledige terugbetaling
- Geen kosten bij foutieve synthese
Automatisch retryen bij tijdelijke fouten
Implementeer backoff-strategieën voor tijdelijke fouten zoals tijdelijke overbelasting. Omdat verzoeken één voor één worden verwerkt, kan wachttijd optreden onder hoge belasting. Retry alleen bij tijdelijke fouten om dubbele kosten te voorkomen bij gelukt verzoek.
- Backoff bij tijdelijke fouten
- Voorkom dubbele kosten bij retry
Cost optimization technieken
De kosten van SpraakZaak zijn direct gekoppeld aan het tekenaantal, inclusief spaties en leestekens. Een efficiënte tekstverwerking begint bij het minimaliseren van overbodige tekens in de input. Door dubbele spaties te verwijderen en onnodige opmaak te strippen, verlaag je het verbruik zonder de luisterervaring aan te tasten. Dit is cruciaal voor bulkverwerking waarbij kleine verschillen zich op grote schaal optellen.
Minimaliseren van overbodige tekens
Controleer je tekst voor spaties tussen leestekens of herhalende tekens die niet nodig zijn voor de syntese. Elke teken bespaart direct geld, aangezien de prijs vaststaat op $0,01 per 1.000 tekens. Een schone input voorkomt ook onnodige pauzes in de gegenereerde audio.
- Verwijder extra spaties tussen woorden en leestekens.
- Strip onnodige HTML-tags vooraleer de tekst naar de API te sturen.
- Vervang lange ellipsen door een enkele punt.
Efficiënte splitsing van teksten
Splits lange teksten strategisch op in blokken van maximaal 4096 tekens per verzoek. Dit voorkomt fouten bij de verwerking en zorgt voor een voorspelbare lading. Het samenvoegen van de audiofiles achteraf is eenvoudiger dan het herstellen van een gebroken verzoek.
- Houd de limiet van 4096 tekens per request strikt aan.
- Splits op zin- of alumniveau voor natuurlijke pauzes.
- Verwerk blokken sequentieel om wachttijden te minimaliseren.
Gebruik van gratis requests bij testen
Gebruik de proefcredit van $0,50 (ongeveer 50.000 tekens) voor integratietests voordat je betaalde credits aanmaakt. Dit stelt je in staat de API-integratie te valideren zonder directe kosten. Mis dit niet tijdens de initiële fase van je workflow.
- Activeer de trial credit bij Google-authenticatie.
- Test voice presets en formats binnen de trial limiet.
- Verbruik de trial snel om veroudering te voorkomen.

Security en authenticatie
De API-sleutel fungeert als uw enige toegangspoort. Bewaar deze streng in omgevingsvariabelen en vermijd hardcoderen in de clientcode. Elke verzoeksessie vereist de header Authorization: Bearer tts-... voor validatie.
Beveiligen van API sleutels
Gebruik een enkele actieve sleutel per account. Deze is uniek en direct geldig voor authenticatie bij elke POST-request naar het endpoint.
- Sla de sleutel op in veilige omgevingsvariabelen.
- Verwijder de sleutel uit zichtbare client-code of logs.
Regelmatig regenereren van keys
Regenereer de sleutel via het dashboard wanneer gewenst. De oude sleutel stopt direct na uitgifte van de nieuwe, waardoor gelijktijdige sessies met de verouderde key onmiddellijk falen.
Beperken van IP addresses (optioneel)
Hoewel de API geen IP-beperkingen native ondersteunt, kunt u dit op uw firewall of proxy-layer regelen. Dit voegt een extra laag beveiliging toe voor uw bulkverwerkingsinfrastructuur.
- Beperk toegang tot bekende server-IPs.
- Monitor ongebruikelijke verzoekpatronen.
Testen en kwaliteit assurance
Kwaliteitsgarantie begint met systematisch testen voordat bulkverwerking start. Door stemmen te valideren op specifieke teksttypen voorkomt u verrassingen bij grote volumes. Dit voorkomt dat foutieve audio's worden gedistribueerd in uw publicatie workflow.
Gebruik de API om snel referentiemateriaal te genereren voor verschillende scenario's. Dit stelt uw team in staat om de meest geschikte voice preset te selecteren op basis van de inhoud en doelgroep van de publicatie.
A/B testen van stemmen
Vergelijk verschillende voice presets zoals 'nova' voor lichte content versus 'atlas' voor nieuws. Genereer dezelfde tekst fragmenten met meerdere stemmen en evalueer de natuurlijkheid en geschiktheid voor de specifieke context.
Documenteer welke stem het beste past bij uw tekststijl. Houd rekening met de taalinstellingen; stel deze expliciet in om foutief gissing te voorkomen, vooral bij tekst in Latijnse karakters die niet Engels is.
- Genereer korte samples van 500 karakters per stem.
- Evalueer de toon op basis van de doelgroep.
- Selecteer de meest geschikte preset voor bulkverwerking.
Verifiëren van uitspraak in context
Controleer of de TTS API vreemde woorden, namen of acronyms correct uitspreekt in de gekozen taal. Sommige namen of technische termen kunnen foutief worden uitgesproken als de taal niet expliciet is ingesteld.
Test de API met typische zinnen uit uw publicaties. Let op de overgang tussen zinnen en de algehele flow van de speech.
Controleren van audio kwaliteit
Luister naar de gegenereerde audio bestanden op achtergrondruis en artefacten. De API produceert schone audio, maar het is belangrijk om te verifiëren dat de kwaliteit voldoet aan uw eisen voor publicatie.
Controleer of het geselecteerde audio formaat (bijv. mp3 of wav) compatibel is met uw distributieplatformen. Houd rekening met de bestandsgrootte en de laadtijden bij het plannen van uw workflow.
Uitrol naar productie
Zodra de API-integratie gereed is, moet je het verbruik nauwkeurig monitoren om onverwachte kosten te voorkomen. Houd je balans en karaktergebruik in de gaten via het dashboard op /get-api-key/. Omdat verzoeken sequentieel worden verwerkt, kan wachttijd optreden onder hoge belasting; monitor je verwerkingssnelheid om knelpunten in je publicatiepipeline tijdig te signaleren.
Stel duidelijke limieten in voor je batchverwerking om de rate limits van 60 verzoeken per minuut niet te overschrijden. Gebruik de karaktertelling als leidraad voor je budget, aangezien elke foutieve synthesekost geld bespaart wordt teruggenomen. Regelmatische controle voorkomt dat je project stilstaat door een lege saldo.
Monitoring van verbruik
Volg je karaktergebruik dagelijks via het dashboard. Houd rekening met de realtime-prestatie van ongeveer 25 tekens per seconde bij lange teksten.
Controleer je saldo regelmatig om te voorkomen dat je batch verwerkt stopt door een onvoldoende saldo.
- Dashboard controle op /get-api-key/
- Karaktertelling bijhouden per batch
Opzetten van alerts bij fouten
Log foutcodes direct in je systeem. Als een synthesefout optreedt, wordt het bedrag volledig teruggenomen, maar je wilt wel weten welke verzoeken mislukten voor eventuele retries.
Stel alerts in voor rate limit overschrijdingen of netwerkfouten om de doorlooptijd van je publicatie niet onnodig te verlengen.
Documenteren van workflow
Beschrijf je integratiestappen voor toekomstige developers. Vermeld welke voice preset en language codes je gebruikt voor consistente output.
Documenteer je splitsingstrategie voor teksten langer dan 4096 karakters, inclusief de methode voor het samenvoegen van audiofragmenten.
Onderhoud en updates
Onderhoud van de TTS-integratie vereist aandacht voor wijzigingen in de API-structuur en prijsmodellen. Omdat SpraakZaak geen SLA biedt, is proactief monitoren essentieel voor een stabiele publicatieworkflow.
Regelmatige updates zorgen ervoor dat uw applicatie compatibel blijft met de huidige limieten en stemconfiguraties zonder onverwachte onderbrekingen tijdens bulkverwerking.
Bijhouden van API changes
Volg de documentatie op /docs/ voor wijzigingen in eindpunten of stemdetails. Houd rekening met mogelijke aanpassingen in rate limits of ondersteunde talen.
Bij wijzigingen in de prijs of karaktertelling, pas uw kostencalculatie direct aan om budgetoverschrijdingen te voorkomen.
- Pas bulkscripts aan bij API-aanpassingen.
Updaten van SDK versies
Gebruik de officiële OpenAI SDK door de base_url aan te passen naar https://api.kb333.info/v1. Houd uw SDK-versie up-to-date voor compatibiliteit met de laatste JSON-structuur.
Test updates in een staging-omgeving voordat ze naar productie gaan om storingen in de audiogeneratie te voorkomen.
- Update SDK regelmatig.
- Test compatibiliteit vooraf.
Review van prijzen en limits
De prijs blijft $10 per miljoen karakters. Controleer regelmatig of uw TRC-20-balans voldoende is voor verwachte volumes.
Houd de rate limit van 60 requests per minuut per key in de gaten. Pas uw batch-strategie aan indien nodig.
Regenereer uw API-key periodiek voor beveiliging, wat de oude key direct deactiveert.
- Monitor balanstoespanning.
- Regenereer keys periodiek.
Veelgemaakte fouten
De meest voorkomende valkuilen bij de integratie van de SpraakZaak API betreffen vaak de vereiste parameters en de limieten van de API. Door deze veelgemaakte fouten te vermijden, voorkom je onnodige kosten en foutmeldingen tijdens de productie.
Vergeten van language parameter
Standaard wordt tekst in Latijns schrift ingeschat als Engels. Voor andere talen zoals Nederlands of Frans is het essentieel om het veld language expliciet in te stellen op de ISO-code (bijv. nl of fr). Zonder deze specificatie kan de synthesepatroon afwijken van de gewenste uitspraak.
Overschrijden van karakter limiet
Elk API-verzoek mag maximaal 4096 tekens bevatten, inclusief spaties en leestekens. Teksten die deze grens overschrijden resulteren in een fout. Voor langere content moet je de tekst vooraf splitsen in kleinere brokken en de audiobestanden achteraf samenvoegen.
Verwarren van tts-1 modellen
Er zijn twee modellen: tts-1 en tts-1-hd. Beide gebruiken dezelfde engine en hebben dezelfde prijs ($0,01 per 1.000 tekens). Het verschil zit hem alleen in de kwaliteit van de audio. Kies tts-1-hd voor hoge eisen, maar betaal niet meer voor hetzelfde model.
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.
Bronnen en verdere literatuur
- Wikipedia
- W3C WAI: making audio and video accessible
- IETF RFC 7845: Ogg Opus
- ISO 639 language codes
- TRON developer hub: TRC-20
- LibriVox public-domain audiobooks
- Node.js documentation
- FFmpeg documentation
- LibriTTS-R paper (arXiv 2305.18802)
- OpenAI API reference: create speech
- openai-node on GitHub
- openai-python on GitHub
