Swedish Text-to-Speech API JSON

You need to generate Swedish speech from text via an HTTP API and get back a predictable JSON payload you can parse in your app. By the end of this guide, you’ll be able to POST Swedish text to the Woord Text-to-Speech convert endpoint, read the official JSON envelope, and safely download or store the resulting MP3 without guesswork.

What this guide covers (and what it doesn’t)

This article focuses strictly on the Woord Text-to-Speech conversion workflow for Swedish (language=sv_SE) using the documented POST /api/convert endpoint. You’ll see the official JSON response envelope, a copy-pasteable curl command, and a minimal Python example that extracts the fields you actually need. We won’t cover unrelated APIs or voice locales, pricing, or quotas, since those details aren’t present here—refer to the product docs where needed.

The Swedish locale and request parameters you must set

To synthesize Swedish speech, set the following form fields in your POST request:

• text: Your input text (URL-encoded when using application/x-www-form-urlencoded). The sample text in the editorial/docs for this locale is “Hello World”.
• gender_voice: Set to male (this is the documented default in the facts provided here).
• language: Use sv_SE for Swedish.

The example curl below also includes speakingRate=1.00. While the core documented fields are text, gender_voice, and language, the provided example includes speakingRate, so we’ll retain it in the sample request without asserting extra behavior beyond what’s shown.

Endpoint, method, headers, and content type

The Woord conversion call is a simple form POST:

• URL: https://www.getwoord.com/api/convert
• Method: POST
• Authorization: Bearer YOUR_API_KEY (replace YOUR_API_KEY with your actual key)
• Accept: application/json
• Body encoding: application/x-www-form-urlencoded form fields

Free accounts cannot call this endpoint. If you don’t have an API key yet, create one after you sign up via Register. Always keep your API key secret and out of client-side code.

Official convert JSON envelope you will parse

On success, Woord returns a compact JSON envelope. This is the official example response from the documentation for this Swedish flow:

{"message":"Your audio has been created!","audio_src":"https://getwoord.s3.amazonaws.com/4273352455515882618255eaaf3c1cbdbe0.55443890.mp3","error":false}

Important notes for production use:

• This exact S3 URL is the documentation fixture. When you run your own request, your audio_src will be a different, newly generated URL. Do not assume this URL persists or belongs to your project.
• Do not hotlink the docs fixture in your app. Treat the returned audio_src from your own request as the source of truth.
• The fields have the following meanings:
  • message: A human-readable status string confirming creation.
  • audio_src: A direct HTTPS URL to the generated MP3 in S3.
  • error: A boolean indicating whether the request failed (false means success).

Copy-pasteable curl for Swedish Text-to-Speech

This curl matches the structure shown in the documentation facts and uses the Swedish locale:

curl "https://www.getwoord.com/api/convert" \
-X POST \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
--data "text=Hello+World&gender_voice=male&language=sv_SE&speakingRate=1.00"

Replace YOUR_API_KEY with your actual key. This request sends URL-encoded form fields. The Accept header ensures you get JSON back. On success, parse audio_src and store or download the MP3.

Minimal Python example with field extraction

The snippet below posts the same form fields, checks the official envelope, and shows how to act on audio_src. It avoids using the docs fixture URL and only uses the URL that your request returns.

import os
import sys
import requests

API_URL = "https://www.getwoord.com/api/convert"
API_KEY = os.getenv("WOORD_API_KEY", "YOUR_API_KEY") # replace in env for production

def synth_sv_se(text, gender_voice="male", speaking_rate="1.00"):
headers = {
"Accept": "application/json",
"Authorization": f"Bearer {API_KEY}",
}
data = {
"text": text,
"gender_voice": gender_voice,
"language": "sv_SE",
"speakingRate": speaking_rate,
}
resp = requests.post(API_URL, headers=headers, data=data, timeout=30)
# If the API uses non-2xx for errors, raise_for_status() will catch it early.
resp.raise_for_status()
payload = resp.json()

# Validate official envelope fields
if not isinstance(payload, dict):
raise ValueError("Unexpected JSON shape")
if payload.get("error") is True:
# The API sets error=false on success; handle the non-success case defensively.
raise RuntimeError(f"Woords TTS conversion reported an error: {payload}")

message = payload.get("message")
audio_src = payload.get("audio_src")

if not audio_src:
raise ValueError("Missing audio_src in response")

print(f"API message: {message}")
print(f"Audio URL: {audio_src}")

# Optional: download the MP3 to a local file you control
# This fetches YOUR returned audio_src, not the docs fixture.
mp3 = requests.get(audio_src, stream=True, timeout=60)
mp3.raise_for_status()
out_path = "speech_sv_SE.mp3"
with open(out_path, "wb") as f:
for chunk in mp3.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)
print(f"Saved: {out_path}")
return out_path

if __name__ == "__main__":
try:
synth_sv_se("Hello World")
except Exception as e:
print(f"Failed: {e}", file=sys.stderr)
sys.exit(1)

Error handling, timeouts, and idempotency tips

Handle network and server errors as you would for any HTTP POST:

• Use a reasonable POST timeout (for example, 30 seconds) and a larger timeout for downloading the MP3, since files can take longer on slow networks.
• Check error strictly via the error field in the JSON envelope. Even with HTTP 200, prefer reading error and inspecting message before assuming success.
• If you implement retries, make them conservative and avoid blind rapid retries that could cause duplicated synthesis requests. Where possible, deduplicate by your own input hash or store results to prevent redundant calls.

Input content and the Swedish locale

Use language=sv_SE for Swedish. The editorial/docs sample text is “Hello World”; your production input can be any text that fits your use case. A few practical tips:

• URL-encode your text in form bodies. For curl, “Hello World” becomes Hello+World. In code, your HTTP library handles encoding when you send a form dict.
• Start with the documented gender_voice=male if you don’t already have a chosen voice.
• If you use speakingRate, keep the default 1.00 unless you’ve validated another value for your content. Do not infer undocumented ranges—verify behavior against the API.

Receiving and storing audio_src

The audio_src returned is a direct HTTPS link to an MP3 in S3. Treat it as follows:

• Do not hardcode or hotlink the documentation’s fixture URL. Your runtime result will be a unique URL for your request.
• Download the MP3 promptly if you need long-term storage or offline processing. Save it in your own bucket or persistent storage and reference that path downstream in your app.
• If you cache results, use a clear key strategy: for instance, a hashed tuple of (text, language, gender_voice, speakingRate), so repeated requests can reuse stored audio and reduce calls.

Production implementation checklist

• Authentication:
  • Always send Authorization: Bearer YOUR_API_KEY.
  • Never embed your API key in client-side code or mobile binaries. Keep it server-side or in secure secrets management.
• Request encoding:
  • Use application/x-www-form-urlencoded form fields: text, gender_voice, language (and speakingRate if you include it as in the example).
  • Set Accept: application/json to receive the JSON envelope.
• Response handling:
  • Parse JSON and check error. Expect fields: message, audio_src, error.
  • Never assume a fixed URL format; use the audio_src you receive.
• Download and persistence:
  • Download audio_src to your own storage for long-term use.
  • Record basic metadata (timestamp, language, voice parameters) so you can audit or regenerate if needed.
• Logging and observability:
  • Log request IDs or input hashes to track duplicates and troubleshooting.
  • Log HTTP status, response time, and whether error=false.

End-to-end example workflow

1) Create a request

POST to /api/convert with:

• text: your Swedish content or the sample “Hello World” for validation
• gender_voice=male
• language=sv_SE
• speakingRate=1.00 (optional, included here per the provided example)

2) Parse the official JSON envelope

From the JSON, read error, message, and audio_src. Proceed only if error is false. Surface message to logs for quick support diagnostics.

3) Store and serve the MP3

Download the MP3 from audio_src into a stable path you control. For example: a versioned directory based on a content hash. From there, your own CDN or app can serve the file without depending on transient URLs.

Troubleshooting common pitfalls

• 403 or 401 errors: Ensure the Authorization header is in the Bearer format and that you’re using a valid API key tied to an account allowed to call this endpoint.
• Non-JSON responses: Verify Accept: application/json and that you’re POSTing form data (data= in curl or form dict in code), not raw JSON.
• Missing audio_src: If error is true or audio_src is absent, do not proceed. Log the full JSON envelope to diagnose the issue.
• Playback glitches: Confirm the MP3 downloaded fully and that your player supports MP3. Re-download on checksum or content-length mismatch.

Frequently asked questions

Q: What’s the exact endpoint and method for Swedish Text-to-Speech?
A: POST https://www.getwoord.com/api/convert with Bearer authorization and form fields text, gender_voice, and language (sv_SE). The example here also includes speakingRate=1.00.

Q: What are the response fields I should rely on?
A: message (status text), audio_src (direct MP3 URL), and error (boolean). Use audio_src to download your audio and check error is false before proceeding.

Q: Can I embed the documentation’s sample S3 URL in my product?
A: No. That audio_src is a documentation fixture. Your production call will return a new URL. Do not hotlink the fixture; always use the URL you receive at runtime.

Q: Do I need JSON in the request body?
A: No. The convert endpoint expects application/x-www-form-urlencoded form fields, not a JSON body.

Q: Where do I get an API key?
A: Create an account and generate a key after you sign up via Register. Free cannot call this endpoint.

Next steps

Implement the curl or Python sample in your backend, confirm you receive the official JSON envelope, and start caching the MP3s you generate. When you’re ready to integrate fully or explore additional parameters, review the Documentation, and if you don’t have credentials yet, create them via Register so you can start synthesizing Swedish speech in your application.