English UK Text-to-Speech API: en_GB Voice to MP3
You need to turn English (UK) text into an MP3 you can stream or download, and you want to do it programmatically. By the end of this guide you’ll be able to authenticate with Woord, submit en_GB text with your chosen voice, and read back a JSON envelope that contains the MP3 URL you can use in your app.
What the endpoint does and when to use it
Woord exposes a text-to-speech conversion endpoint that takes your text, a UK English language code (en_GB), and a voice selection, then returns an MP3 URL in a JSON envelope. Use it anytime you need a server-side or backend-friendly way to generate speech on demand, pre-generate voiceovers, or cache audio for repeated playback.
The request is a POST to /api/convert with Bearer authorization and form fields (multipart/form-data), not JSON. The response is JSON and includes a field you will actually use in production: the MP3 URL (audio_src). The sample response below shows the structure of this envelope.
Key practical constraints to plan for in your integration:
- Language code: en_GB (English UK).
- Form fields only: text, gender_voice, language=en_GB.
- Per-file limit: 10k characters of input text.
- Trial: 8 days and 20k characters total. Free plans cannot call /api/convert.
- No MCP required.
If you need the full set of supported values and the latest behavior, consult the Documentation.
Account, auth, and plan requirements
You’ll authenticate with a Bearer token. Copy your key from your dashboard after sign-up. The Free plan cannot call /api/convert; you’ll need the trial (8 days / 20k characters) or a paid plan to actually invoke the conversion. The Starter plan is $9.99/mo. These limits help you size your integration and testing cycles.
Auth details:
- Header: Authorization: Bearer YOUR_API_KEY
- Do not send JSON in the body; use form fields.
Quickstart flow: en_GB to MP3
- Register for an account — you’ll get an 8-day, 20k-character trial to test the API.
- Copy your Bearer key from the dashboard (note: Free cannot call convert).
- Send a POST to /api/convert with language=en_GB, plus your text and gender_voice.
- Read audio_src from the JSON envelope and use it to fetch or stream the MP3.
Make the request (curl)
The following is the official convert request. You can copy-paste it and swap YOUR_API_KEY and the form values for your use case.
Important: language must be en_GB to get a UK English voice. The body must be form data with fields text, gender_voice, and language.
curl "https://www.getwoord.com/api/convert" -X POST \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
--data "text=Hello+World&gender_voice=male&language=en_GB&speakingRate=1.00"
Understand the JSON response
The convert endpoint responds with a JSON envelope that includes the MP3 URL. Below is the official convert envelope you’ll see. The audio file name shown is for documentation only and will differ in your own calls. Do not hotlink the sample URL; always use the audio_src you receive from your request.
{"message":"Your audio has been created!","audio_src":"https://getwoord.s3.amazonaws.com/4273352455515882618255eaaf3c1cbdbe0.55443890.mp3","error":false}
How to use it:
- audio_src: The HTTPS URL of the generated MP3. This is what you store or stream. Expect a new, unique URL on each successful conversion request.
- success: If present and false, the conversion failed; you should not attempt to fetch audio_src.
- Other fields: If the envelope includes message or error fields, log them for troubleshooting and surface an actionable error to the user.
Handling missing or false values:
- If success is present and false, or if audio_src is missing or empty, treat the job as failed. Do not attempt to download audio.
- Retry logic should be constrained and backoff-based for transient errors. If the response indicates a validation problem (e.g., missing text or invalid language), do not retry without fixing the input.
Units, timezones, and caching considerations:
- Characters are counted in plain text units. The per-file limit is 10k characters; split longer text and stitch audio in your application if needed.
- If the envelope includes timestamps, treat them as UTC unless the docs state otherwise. If no timestamps are present, your app can use its own request time.
- You can cache audio_src and the downloaded MP3 in your storage to avoid re-conversion for identical inputs. The S3 URL in the sample is not yours; always use your own audio_src values.
Example: Python request and response handling
This Python snippet posts form fields to /api/convert with Bearer auth, then validates success and extracts audio_src. It also demonstrates how to guard against missing values and avoid using sample URLs from documentation.
import os
import sys
import requests
API_KEY = os.getenv("WOORD_API_KEY", "YOUR_API_KEY")
API_URL = "https://www.getwoord.com/api/convert"
def convert_to_mp3_en_gb(text, gender_voice):
# Enforce the per-file 10k character limit client-side when possible
if len(text) > 10_000:
raise ValueError("Text exceeds 10k characters per file. Split your input.")
headers = {
"Authorization": f"Bearer {API_KEY}",
}
data = {
"text": text,
"gender_voice": gender_voice, # See docs for allowable values
"language": "en_GB",
}
resp = requests.post(API_URL, headers=headers, data=data, timeout=60)
resp.raise_for_status() # Raises for non-2xx
envelope = resp.json()
# Gracefully handle success flag and missing fields
success = envelope.get("success", True)
if not success:
# Log full envelope for diagnostics; surface safe message to the caller
raise RuntimeError(f"Conversion failed: {envelope}")
audio_src = envelope.get("audio_src")
if not audio_src:
raise RuntimeError(f"No audio_src returned: {envelope}")
# Never hotlink sample URLs you see in docs; always use your own URL here
return audio_src
if __name__ == "__main__":
try:
url = convert_to_mp3_en_gb(
text="Hello from Woord! This is a UK English sample.",
gender_voice="female"
)
print("MP3 URL:", url)
except Exception as e:
print("Error:", e, file=sys.stderr)
sys.exit(1)
Production notes that save time
- Text segmentation: If your content can exceed 10k characters, split it at sentence or paragraph boundaries and submit multiple conversions. Keep track of the resulting audio_src URLs and stitch the MP3s server-side if needed.
- Input hygiene: Strip control characters and normalize whitespace before sending text. This reduces surprises in character counts and improves speech quality.
- Idempotency by content hashing: When appropriate, compute a hash of (language, gender_voice, text) and cache the resulting audio_src and the MP3 file. Reuse it for identical requests to avoid re-conversion and character spend.
- Error handling: Treat non-2xx HTTP responses as retriable only if the failure is transient. If the JSON envelope includes success=false or validation messages, fix inputs before retrying.
- Security: Store your Bearer key server-side. Do not expose it in frontend code.
Troubleshooting
- HTTP 401 or 403: Confirm you’re using Bearer auth with a valid key. The Free plan cannot call /api/convert.
- success=false in response: Inspect any message or error fields returned. Common issues include missing form fields, invalid language, or disallowed voice values.
- Missing audio_src: Treat as a failed conversion and do not fetch audio. Log the envelope and open a ticket if it persists with valid inputs.
- Unexpected language/accent: Ensure language is exactly en_GB. If you’re repurposing code from another locale, verify you changed the language field.
FAQ
What parameters are required to generate UK English audio?
Send a POST to /api/convert with form fields: text, gender_voice, and language=en_GB. Include your Bearer token in the Authorization header.
Can I use the Free plan to test conversion?
No. Free cannot call convert. Use the 8-day / 20k-character trial or a paid plan.
How many characters can a single conversion include?
Up to 10k characters per file. Split longer input and submit multiple conversions.
What does audio_src represent in the response?
It’s the HTTPS URL for your generated MP3. Store or stream it from your app. Do not hotlink the sample URL shown in documentation; use the one returned to your request.
Where can I find valid values for gender_voice?
Refer to the API’s voice selection guidance in the Documentation. Pass your chosen value along with language=en_GB.
Convert en_GB text to MP3 now. Start your 8-day, 20k-character trial and get a Bearer key to go live: Register.
