Dutch Text-to-Speech API: nl_NL Voice to MP3
You need to turn Dutch (nl_NL) text into an MP3 file you can stream or download, and you want a simple API that returns a ready-to-use URL. By the end of this guide you’ll be able to authenticate, post text to Woord’s Dutch Text-to-Speech endpoint, and reliably extract the MP3 URL for use in your web or mobile app.
What you’ll build and when to use it
You’ll integrate a single HTTP POST call that converts Dutch text (language code nl_NL) to speech and returns an MP3 URL. This is useful for voice-over automation, accessibility features, IVR prompts, and any workflow where you need a programmatic, repeatable text-to-audio pipeline.
The flow is straightforward: authenticate with a Bearer key, POST your text with language=nl_NL to the convert endpoint, then read the audio_src property from the JSON response. That URL points to the generated MP3.
Account, access, and pricing basics
- Free plans cannot call the convert endpoint.
- There is an 8-day trial with 20k characters to test your integration.
- The Starter plan is $9.99/mo.
To begin, create an account and start the trial so you can call the convert API without interruptions: Register.
The conversion endpoint and parameters
The Woord conversion API is a POST to /api/convert that accepts form fields. To synthesize Dutch, set language=nl_NL. You authenticate with a Bearer token in the Authorization header. The API returns a JSON envelope that includes an audio_src URL for the resulting MP3.
If the official example below shows a different language, switch the language form field to nl_NL for Dutch output.
Copy-paste request (curl)
Use this request as-is to validate your pipeline. Replace YOUR_API_KEY with your actual Bearer key from your Woord account. If the sample uses another language, change language to nl_NL.
curl "https://www.getwoord.com/api/convert" -X POST -H "Authorization: Bearer YOUR_KEY" --data "text=Hello+World&gender_voice=male&language=nl_NL&speakingRate=1.00"
Official response format
You’ll receive a JSON envelope like the one below. In typical use, you will check whether the call was successful and extract audio_src. If success is false, you should inspect error-related fields (if present) and avoid assuming audio_src exists.
{"message":"Your audio has been created!","audio_src":"https://getwoord.s3.amazonaws.com/4273352455515882618255eaaf3c1cbdbe0.55443890.mp3","error":false}
What the fields mean in practice:
- success: Boolean that indicates whether the conversion completed. Always check this before reading other fields.
- audio_src: The absolute URL to the generated MP3. This is the value you’ll stream or download.
- Other fields: If present, these may include identifiers or messages for debugging. Treat missing fields defensively—guard your code against absent properties.
End-to-end example in Python
This Python snippet posts Dutch text with language=nl_NL, validates success, extracts audio_src, and prints it. It also handles the case where the response is unsuccessful or audio_src is missing.
import os
import sys
import requests
API_BASE = "https://www.getwoord.com"
API_KEY = os.getenv("WOORD_API_KEY", "YOUR_API_KEY")
def convert_to_mp3_nl(text):
url = f"{API_BASE}/api/convert"
headers = {
"Authorization": f"Bearer {API_KEY}",
}
# Form-encoded fields. Include language=nl_NL to synthesize Dutch.
data = {
"language": "nl_NL",
"text": text
}
resp = requests.post(url, headers=headers, data=data, timeout=30)
# Basic transport-level checks
resp.raise_for_status()
payload = resp.json()
# Defensive checks for the envelope and fields
if not isinstance(payload, dict):
raise ValueError("Unexpected response type")
success = payload.get("success")
if success is not True:
# Prefer a message or code if present; if not, provide a generic error
message = payload.get("message") or payload.get("error") or "Conversion failed"
raise RuntimeError(f"API indicated failure: {message}")
audio_src = payload.get("audio_src")
if not audio_src:
raise RuntimeError("No audio_src returned in a successful response")
return audio_src
if __name__ == "__main__":
sample_text = "Hallo! Dit is een Nederlandse tekst-naar-spraak test."
try:
url = convert_to_mp3_nl(sample_text)
print(f"MP3 URL: {url}")
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
sys.exit(1)
Go-live checklist
1) Create your account
Start your 8-day trial to unlock /api/convert: Register.
2) Get your Bearer key
From your account area, copy the Bearer token you’ll use in the Authorization header.
3) POST to /api/convert
Send your text along with language=nl_NL. Keep your Authorization header set to Bearer YOUR_API_KEY.
4) Read audio_src
On success, parse the JSON response and read audio_src. That URL is your Dutch MP3.
Error handling and resilience
- Always check success before reading audio_src. If it’s false, look for a message or error field and do not assume audio_src is present.
- Guard against missing or null fields. Treat the response as untrusted input and perform presence checks.
- Do not retry blindly. For failures that look transient (network timeouts), a short backoff can help. If the envelope indicates a request problem (e.g., missing fields), fix inputs first.
- Free plans cannot call convert. If you receive auth-related errors, verify you’re on a trial or paid plan and that your Bearer key is correct.
Data handling, caching, and file delivery
The key output is an MP3 file accessible via the audio_src URL. Treat this URL as a downloadable asset that you can cache or store within your own infrastructure if your application needs longevity or offline availability. Since response headers or expiry details are not specified here, decide on application-level caching based on your usage patterns and consult the Documentation for any constraints relevant to hosting or redistribution.
Billing units commonly tie to the amount of text processed; the trial allocates 20k characters over 8 days. For production, design your integration to keep track of processed character counts in your application logs if you need internal monitoring. When storing your own copies of audio, include the original text and language code (nl_NL) alongside the cached MP3 metadata so future re-syntheses are traceable.
Validation tips that save time
- Start with short text to verify end-to-end success and that audio_src is present. Then scale to longer inputs.
- If you see a successful envelope but cannot play audio, paste audio_src into a browser to confirm it downloads or streams correctly. Then move on to in-app playback.
- When supporting multiple languages, ensure you explicitly set language per request. For Dutch, use nl_NL.
- If your production system requires deterministic filenames, generate them in your app and store the fetched MP3 accordingly rather than relying on the full URL as the primary key.
Common variations
Many teams wrap /api/convert behind their own service to normalize inputs and outputs. For example, you can create a small service that standardizes text cleanup (e.g., whitespace normalization), enforces language=nl_NL, logs the text length for cost awareness, and stores the resulting audio locally so client apps don’t need direct API access. This approach also centralizes error handling and makes future changes to the integration less disruptive.
Troubleshooting
- 401/403-like behavior: Double-check that you’re not on the free tier, confirm your trial or subscription status, and verify the Authorization: Bearer header contains your current key.
- success=false: Inspect message or error fields if present. Validate that language is set to nl_NL and that your text meets any documented constraints in the Documentation.
- Empty or missing audio_src: Treat it as an error even if HTTP status is 200. Don’t attempt to fetch audio without a valid URL.
- Inconsistent playback: Save the MP3 locally or to your own CDN after the first successful conversion if your application needs consistent long-term access.
FAQ
Can I call /api/convert on a free plan?
No. Free cannot call convert. Use the 8-day trial or a paid plan.
What language code should I use for Dutch?
Use language=nl_NL.
How do I authenticate?
Include Authorization: Bearer YOUR_API_KEY on each request.
Where is the MP3?
Read the audio_src field in the JSON response. That is the direct URL to the generated MP3.
How is usage measured?
The trial provides 20k characters over 8 days. For ongoing limits and plan details, refer to your account and the Documentation.
Ready to convert Dutch text to MP3? Start your 8-day trial and get your Bearer key: Register. Then POST with language=nl_NL and read audio_src to plug high-quality Dutch speech into your app within minutes.
