Veelgestelde vragen
Hoe vraag ik een API key aan?
Registreer je op https://r38.info/get-api-key/ via Google of e-mail met wachtwoord. Je ontvangt direct een actieve sleutel. Elke account heeft één sleutel; bij het opnieuw aanmaken stopt de oude direct.
Welke JSON velden zijn verplicht?
De velden model, input en voice zijn verplicht. Model is 'tts-1' of 'tts-1-hd', input is de tekst (max 4096 karakters) en voice is een van de acht presets. Optional zijn response_format, speed en language.
Hoe pas ik de base URL aan voor de OpenAI SDK?
Stel de base_url van de OpenAI SDK in op https://api.r38.info/v1. Gebruik dezelfde verzoekstructuur als de OpenAI speech endpoint. Zorg dat je autorisatie-header de juiste API-sleutel van SpraakKern bevat.
Wat is het verschil tussen tts-1 en tts-1-hd?
Er is geen technisch of prijsverschil tussen tts-1 en tts-1-hd. Ze gebruiken dezelfde engine en hebben dezelfde prijs. Je kunt beide modellen gebruiken voor dezelfde resultaten en kosten per karakter.
Hoe stel ik de snelheid in?
Gebruik het veld 'speed' in de JSON-body. De waarde moet tussen 0.25 en 4.0 liggen. Standaard is de snelheid 1.0. Dit verandert de generatiesnelheid van de spraakuitvoer zonder de toon of stem te beïnvloeden.
Wat gebeurt er als ik een ongeldige voice gebruik?
De API keert een fout terug voor het verzoek. Omdat het verzoek mislukt, worden er geen kosten in rekening gebracht. De foutmelding geeft aan dat de opgegeven voice niet tot de acht beschikbare presets behoort.
Kan ik meerdere talen in één verzoek mixen?
Ja, zolang de tekst binnen de 4096 karakters blijft. Als je language niet specificeert, wordt deze geraden op basis van het script. Voor niet-Engelse tekst in Latijns schrift is het aanbevolen language expliciet in te stellen.
Hoe verwerk ik de response data?
De response bevat het gegenereerde audiobestand direct in de body. Je kunt dit bestand opslaan of verwerken. De ondersteunde formaten zijn mp3, wav, opus, flac en pcm, afhankelijk van je ingestelde response_format parameter.
Wat zijn de limieten voor tekstlengte?
Elk verzoek mag maximaal 4096 karakters tekst bevatten. Voor langere teksten moet je deze splitsen in delen van maximaal 4096 karakters. De gegenereerde audiobestanden van de delen kun je daarna aan elkaar plakken.
Wordt er caching toegepast op verzoeken?
Er wordt geen caching vermeld in de productspecificaties. Elke request wordt individueel verwerkt door de engine. Onder belasting kunnen verzoeken in een wachtrij komen, wat de verwerkingstijd beïnvloedt, maar er is geen cache-mechanisme beschreven.
Hoe herken ik een mislukt verzoek in de response?
Een mislukt verzoek resulteert in een HTTP-foutstatuscode en een foutbericht in de response body. Bij een fout wordt het bedrag van het verzoek volledig teruggenomen op je saldo, dus je wordt niet aangerekend.
Kan ik de API gebruiken in een backend server?
Ja, de API is ontworpen voor server-side integratie via HTTP POST requests. Je kunt de OpenAI SDK of gewone HTTP-clients gebruiken. De authenticatie verloopt via de Bearer token in de Authorization header.
Is er een limit aan het aantal gelijktijdige verzoeken?
Er is een limiet van 60 requests per minuut per sleutel (10 voor de eerste top-up). Verzoeken worden sequentieel verwerkt, dus onder belasting kan een verzoek in de wachtrij komen. Er is geen expliciete limiet aan parallelle verbindingen.
Hoe lang zijn de gegenereerde audio bestanden?
De lengte hangt af van de tekst. Bij lange teksten is de generatiesnelheid ongeveer gelijk aan realtime (25 tekens per seconde). Korte zinnen kunnen enkele seconden duren. De bestanden zijn direct beschikbaar na verwerking.
Eerste verzoek
curl
curl https://api.r38.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.r38.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.r38.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
Je start met het aanmaken van een API key via de /get-api-key/ pagina. Je kunt inloggen met Google of e-mail. Een account bevat precies één actieve sleutel die je gebruikt voor authenticatie bij alle API-verzoeken.
De sleutel werkt als een Bearer token in de Authorization header. Elke request moet deze header bevatten om krediet te verbruiken en audio te genereren via de endpoint.
API Key ophalen
Ga naar /get-api-key/ en log in met Google of e-mail. Je ziet direct je unieke sleutel, startbalans en het aantal restererende tekens. Deze sleutel is nodig voor alle API-calls.
Bearer token
Voeg Authorization: Bearer tts-<jouw-sleutel> toe aan je HTTP-headers. Zonder deze header wordt je verzoek geweigerd met een 401-fout. De sleutel is specifiek voor deze API en werkt met de OpenAI SDK structuur.
Key vervangen
Je kunt op elk moment een nieuwe sleutel genereren via je dashboard. De oude sleutel wordt direct ongeldig zodra de nieuwe wordt gegenereerd. Dit is nuttig bij mogelijke lekkage of bij het migreren van projecten.
Eerste verzoek (Curl)
De API accepteert tekst via een JSON-body. Elk verzoek mag maximaal 4096 tekens bevatten; voor langere teksten splitst u de input en voegt u de audiobestanden achteraf samen. De snelheid varieert van 0.25 tot 4.0.
JSON body structuur
De request body bevat velden zoals model (tts-1 of tts-1-hd), input (de tekst), voice (een van de 8 presets), response_format (mp3, wav, opus, flac, pcm) en optioneel speed (0.25–4.0). Gebruik het veld language met een ISO-code als de tekst niet Engels is, anders wordt het script gebruikt.
Voorbeeld commando
Gebruik dit curl-commando om audio te genereren. Vervang tts-... door uw eigen sleutel.
`curl -X POST https://api.r38.info/v1/audio/speech -H "Authorization: Bearer tts-..." -H "Content-Type: application/json" -d '{"model": "tts-1", "input": "Hallo wereld", "voice": "nova", "response_format": "mp3"}' -o output.mp3`
Response format
De API retourneert het audiobestand direct in de response body met de juiste MIME-type header. Bij fouten ontvangt u een JSON-object met een foutmelding. Mislukte synthesen worden volledig verrekend.
Integratie met OpenAI SDK
De SpraakKern API volgt exact dezelfde requeststructuur als de OpenAI speech endpoint. Dit betekent dat je bestaande Python- of Node.js code met minimale aanpassingen kunt gebruiken. Je hoeft geen nieuwe client te schrijven; je hoeft alleen de base_url aan te passen naar https://api.r38.info/v1.
Door de compatibiliteit met de officiële OpenAI SDKs is de integratie direct mogelijk. Je gebruikt dezelfde methoden en objecten, wat fouten minimaliseert bij het porten van bestaande TTS-workflows naar onze infrastructuur.
Base URL aanpassen
Verander de basis-URL in je SDK-configuratie naar https://api.r38.info/v1. Dit zorgt ervoor dat alle verzoeken naar onze endpoints gaan in plaats van die van OpenAI.
Je gebruikt dezelfde API-key die je op /get-api-key/ hebt gevonden, maar moet deze expliciet meegeven. De authenticatie via Bearer token werkt identiek.
- Base URL: https://api.r38.info/v1
- Endpoint: POST /v1/audio/speech
Code voorbeeld Python
Hieronder zie je een minimale implementatie met de openai Python library. Zorg dat je de library hebt geïnstalleerd en je key hebt ingesteld in de environment variable OPENAI_API_KEY of expliciet meegeeft.
Het verzoek gebruikt het tts-1 model. Voor hogere kwaliteit kun je tts-1-hd kiezen; de prijs en structuur blijven hetzelfde.
- import openai
- client = openai.OpenAI(base_url="https://api.r38.info/v1")
- speech = client.audio.speech.create(...)
- with open("speech.mp3", "wb") as f:
- f.write(speech.content)
Compatibiliteit
De SDK verwacht een JSON-body met de velden model, input, voice en response_format. Deze velden zijn identiek aan die van OpenAI.
Je kunt direct doorgaan met bestaande libraries die de OpenAI speech endpoint ondersteunen. Geen extra adapters nodig.
- Ondersteunde SDKs: officiële OpenAI clients (via base_url aanpassing)
- Request shape: identiek aan OpenAI
- Geen extra wrappers nodig
Parameters
De API accepteert twee modelnamen, tts-1 en tts-1-hd. Beide modellen gebruiken dezelfde onderliggende engine en hebben dezelfde tarieven, wat betekent dat er geen prijsverschil is tussen de twee opties bij het versturen van je verzoek.
Kies simpelweg het model dat het beste past bij je workflow. Omdat de prestaties identiek zijn, kun je switchen zonder de kosten te beïnvloeren. Het veld model is vereest in elke JSON-body.
Model keuze
Kies tussen tts-1 en tts-1-hd. Beide modellen gebruiken exact dezelfde synthesizer-engine en hebben identieke tarieven van $10 per miljoen tekens.
Er is dus geen prijsverschil of kwaliteitsverschil in de engine zelf. Je kunt zonder risico schakelen tussen de twee modelnamen afhankelijk van je voorkeur.
Voice selectie
Je kunt kiezen uit acht vaste stemmen: aria, nova, luna, sage (vrouwelijk); felix, milo, atlas, orion (mannelijk). Elke stem ondersteunt alle 23 beschikbare talen.
De API gendt automatisch de taal aan de hand van het script. Voor Latijnse teksten buiten het Engels moet je het veld language expliciet instellen om fouten te voorkomen.
- aria: warme, duidelijke verteller
- nova: helder, energiek
- luna: zacht, verhalenverteller
- sage: rustig, instructief
- felix: energiek, promotie
- milo: vriendelijk, gesprekken
Snelheid instellen
De snelheid kun je instellen tussen 0.25 en 4.0. Dit verandert de uitspraaktempo zonder de toonhoogte aan te passen.
Snellere teksten besparen geen characters, maar kunnen de luisterervaring beïnvloeren. Houd rekening met wachttijden in de queue bij hoge volumes.
Response formats
De API retourneert de gegenereerde audio als binaire data in de response body. Het formaat wordt bepaald door het response_format veld in je request: je kunt kiezen tussen MP3, WAV, Opus, FLAC of PCM. Elke vorm wordt direct beschikbaar gesteld voor directe opslag of verwerking.
MP3, WAV, Opus
MP3 is de standaard voor efficiënte opslag. WAV biedt lossless kwaliteit voor directe verwerking. Opus biedt hoge compressie.
- MP3: compact en breed ondersteund.
- WAV: lossless, hoge bitrate.
- Opus: efficiënte compressie.
Binaire data
De audio bytes worden direct in de response body meegegeven zonder extra JSON enveloppe. Dit maakt het verwerken van grote hoeveelheden data voor ML-modellen direct en efficiënt.
Headers
De response bevat Content-Type headers die exact overeenkomen met het gekozen formaat. Gebruik deze headers om de data correct te decoderen in je applicatie of script.

Foutafhandeling
Bij een fout wordt geen audio teruggegeven en blijven de characters op je saldo staan. De API retourneert een foutmelding met een duidelijke oorzaak, zoals een ongeldig model of een overschreden limiet. Dit voorkomt dat je betaalt voor mislukte synthese.
Foutcodes variëren van 400 (verkeerde invoer) tot 500 (serverproblemen). Controleer altijd de response body voor de specifieke foutmelding voordat je opnieuw probeert te verzenden of je request aanpast.
Status codes
Een 200-statuscode betekent dat de audio succesvol is gegenereerd. Afwijkingen van deze code wijzen op een probleem in je request of bij de server. Bij een fout blijft je balans intact.
- 400: Ongeldige parameters of modelnaam.
- 401: Verkeerde of verlopen API key.
- 429: Te veel verzoeken in korte tijd.
- 500: Interne serverfout tijdens synthesen.
Gebruik van foutmeldingen
De JSON-response bevat een beschrijvende foutmelding. Lees deze zorgvuldig om te begrijpen waarom het verzoek faalde, bijvoorbeeld een tekst die te lang is of een ongeldige voice ID.
Controleer of je key correct is meegegeven in de Authorization header. Zelfs kleine typfouten in de header kunnen leiden tot een 401-fout.
Retries
Implementeer een backoff-strategie bij 500- of 429-statuscodes. Wacht kort tussen pogingen om de queue te ontlasten.
Voor 400-fouten is herhalen zinloos; corrigeer eerst de invoer. Bij 429 wacht je tot de limiet van 60 requests per minuut is gereset.
Rate Limits
Je account is beperkt tot maximaal 60 requests per minuut per API-key. Als je account pas is aangemaakt en nog geen top-up heeft, geldt een lager limiet van 10 requests per minuut.
60 requests per minuut
Het limiet geldt per API-key. Houd er rekening mee dat een enkel verzoek voor lange teksten meerdere interne calls kan genereren, die meetellen tegen dit quota.
Backoff strategie
Implementeer backoff bij 429-fouten. Wacht kort voor je het verzoek opnieuw probeert om de server niet te overbelasten.
Queue verwerking
Requests worden sequentieel verwerkt. Onder hoge belasting kan een verzoek in de wachtrij komen te staan, wat de totale verwerktijd verlengt.
Voices endpoint
Gebruik de GET /v1/voices endpoint om de beschikbare stemmen en hun ondersteunde talen op te halen. Dit stelt je in staat om programmatisch de juiste voice parameter te selecteren voor je dataset.
De API retourneert een lijst met alle 8 beschikbare presets, inclusief hun unieke ID's en de lijst met talen die elke stem kan spreken.
Lijst ophalen
Maak een GET verzoek naar /v1/voices. Je ontvangt een JSON array met alle beschikbare stemmen. Elke entry bevat de voice ID, naam, gender en de lijst van ondersteunde taalcodes.
- Endpoint: GET https://api.r38.info/v1/voices
- Response: JSON array van stem objecten
- Geen authenticatie vereist voor de lijst
Details per stem
Elke stem heeft een uniek ID (bijv. 'aria', 'nova', 'milo'). Deze IDs gebruik je in de voice parameter van je speech request. De 8 presets zijn vastgesteld en kunnen niet worden aangepast of gekloond.
- 8 vaste presets: aria, nova, luna, sage, felix, milo, atlas, orion
- Bijv. 'aria' voor een warme narrator, 'atlas' voor nieuws
- Geen aangepaste stemmen of cloning mogelijk
Talen per stem
Elke stem kan elke van de 23 ondersteunde talen spreken. Specificeer de ISO taalcode in je request om de correcte uitspraak te garanderen. Zonder language parameter wordt de taal geraden (Latin tekst -> Engels).
Luister naar de 8 stemmen
Elk voorbeeld hieronder is gegenereerd door deze API met dezelfde zin. Van registratie tot de eerste audio file duurt het slechts enkele minuten.
23 talen
Elke stem kan elke van deze talen spreken.
