French (Canada) TTS API: First Request with curl and JSON

You need a working, copy-pasteable first request that converts text to French (Canada) speech using Woord. By the end of this guide, you will send a POST to the conversion endpoint with curl, do the same in Python, and understand the JSON response you will handle in your app.

What you will build

You will make one authenticated request to generate a French (Canada) MP3 from a short text. The request will use the language code fr_CA and a male voice (the documented default). You will also learn how to read the minimal response fields you need to continue in your own workflow.

Prerequisites and access

You need an API key from Woord to call the conversion endpoint. Plans that include API access can invoke the /api/convert route; free accounts cannot call convert. If you have not created an account and obtained an API key yet, sign up first.

- Create your account: Register
- Keep your key secure; you will pass it via the Authorization: Bearer header when calling the API.

Endpoint and parameters

This guide targets the conversion endpoint that returns a URL to an MP3 generated from your text:

- Method: POST
- URL: https://www.getwoord.com/api/convert

Form fields used here:

• text: The text you want to synthesize. For this locale sample, use Hello World.
• gender_voice: Voice gender. Using male (the documented default).
• language: The locale code. For French (Canada), use fr_CA.
• speakingRate: Decimal rate multiplier as a string. Use 1.00 for normal speed.

Headers:

• Accept: application/json
• Authorization: Bearer YOUR_API_KEY

Notes that save time:

• Content type: Using standard form fields is sufficient; curl’s --data flag sends application/x-www-form-urlencoded by default.
• Locale: Use the exact language code fr_CA. Do not substitute other variants.
• Text encoding: URL-encode your text for curl or send as form data in your code client; non-ASCII characters should be encoded by your HTTP library.
• Rate value: speakingRate accepts a numeric string (e.g., 1.00). Keep two decimal places if you want deterministic serialization across clients.
• Result handling: The API returns a JSON envelope that includes an audio_src pointing to an MP3. Store that link or download the file on your side for reuse and latency control.

Make your first request with curl

Run this from your terminal. Replace YOUR_API_KEY with your actual token.

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=fr_CA&speakingRate=1.00"

If successful, the API returns JSON containing a status message and a URL to your generated MP3. The URL value will be unique to your request.

Do it in Python

This short Python snippet uses requests to call the same endpoint and prints the message and audio URL. Keep the header name and form fields exactly as shown.

import requests

url = "https://www.getwoord.com/api/convert"
headers = {
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_KEY",
}
data = {
"text": "Hello World",
"gender_voice": "male",
"language": "fr_CA",
"speakingRate": "1.00",
}

resp = requests.post(url, headers=headers, data=data, timeout=30)
resp.raise_for_status()

payload = resp.json()
print("message:", payload.get("message"))
print("audio_src:", payload.get("audio_src"))

# Optional: download the MP3 to local storage if you plan to serve it from your CDN
audio_url = payload.get("audio_src")
if audio_url:
mp3 = requests.get(audio_url, timeout=60).content
with open("woord_fr_CA_hello_world.mp3", "wb") as f:
f.write(mp3)

In production, persist the response JSON (or at least the audio_src) alongside the original text to avoid regenerating audio repeatedly.

Understand the JSON response

The official response envelope from the documentation looks like this (values are illustrative; your audio_src will be different):

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

Fields you will typically use:

• message: Human-readable status string for basic logging.
• audio_src: HTTPS link to the generated MP3 hosted on S3. Store this or download the MP3 if you want to cache or distribute the file via your own storage.
• error: Boolean indicating whether the request failed. Check this before using audio_src.

Implementation notes:

• Availability: The audio file becomes available immediately after a successful response. If you programmatically download it, retry once on 5xx or transient network errors.
• Caching: For repeated, identical inputs (same text, language, voice, and rate), consider caching the audio result on your side to reduce request volume and startup latency.
• Hotlinking: While the response includes a direct S3 URL, production apps often download the file and serve it from their own origin to maintain control over caching and availability.

Locale specifics for French (Canada)

This guide targets French (Canada) with language=fr_CA and gender_voice=male. The sample text from the documentation for this locale is Hello World. Keep these exact values when testing to match the examples above. Once your first request succeeds, swap in your real French (Canada) content and adjust speakingRate as needed.

Error handling and troubleshooting

Authentication and access

- 401/403 responses: Verify you are sending Authorization: Bearer YOUR_API_KEY and that your plan allows convert. Free accounts cannot call convert.

- Key rotation: If you rotate your key, update it in all environments sending requests.

Request formatting

- Content type: Ensure you send form fields (either as URL-encoded data in curl or as form data via your HTTP library). Missing fields or typos in keys (language vs. lang) will cause errors.

- Locale code: Use fr_CA literally. Do not use fr or fr-CA unless the documentation explicitly lists them as supported codes. This guide uses the exact documented code for French (Canada).

Response processing

- JSON parsing: Always parse JSON and check error before using audio_src. If error is true or audio_src is missing, log the message field and handle gracefully.

- Audio retrieval: If you immediately fetch the MP3 from audio_src, use a reasonable timeout and a single retry on transient failures to avoid duplicating synthesis requests.

Production tips

• Idempotency by content: Maintain a deterministic cache key from text + language + gender_voice + speakingRate to avoid unnecessary repeat conversions.
• Observability: Log the message, a hash of your input text, and the audio_src to trace any playback issues back to specific conversions.
• Data hygiene: Normalize whitespace in text before sending. For curl, URL-encode correctly; in code, rely on your HTTP library to handle encoding.
• Rate configuration: Keep speakingRate as a string with two decimals to avoid locale-specific float formatting surprises when constructing form data.
• Security: Never expose YOUR_API_KEY client-side. Call the API from your backend or through a secure proxy.

FAQ

Can I call the convert endpoint from a free account?
Free accounts cannot call convert. Use a plan with API access to invoke /api/convert.

What locale code should I use for French (Canada)?
Use language=fr_CA exactly as shown. This guide’s examples and the sample text are aligned with that locale.

Which voice gender is used by default?
The documented default is male. This guide sets gender_voice=male explicitly to be unambiguous.

What is the speaking rate format?
Use a decimal string like 1.00 for normal speed. Keep two decimals to ensure consistent serialization across environments.

How do I store the resulting audio?
Read audio_src from the JSON and either persist the URL or download the MP3 to your storage. For stable delivery and caching control, many apps download and serve the file from their own origin.

Next steps

Register for an API key and ship your first French (Canada) TTS request in minutes. Start here: Register. For parameter details and broader options, see the Documentation.