Male Voice Text-to-Speech API: en_US to MP3

You need to turn plain English (en_US) text into a male-voice MP3 you can play in your app. By the end of this guide you’ll be able to call Woord’s Text-to-Speech API with a Bearer token, request a male voice, and reliably download the MP3 from the audio_src URL that the API returns.

What you will build

You will integrate a minimal, production-ready flow that:

• Sends text plus language=en_US and gender_voice=male to Woord’s convert endpoint.
• Receives a JSON response that includes an audio_src URL for an MP3.
• Downloads the MP3 and stores it locally or in your own object storage.

Woord’s Documentation defaults to male voice for the API, but you will explicitly send gender_voice=male so your code is unambiguous and easy to maintain.

Plan, pricing, and limits to keep in mind

• Starter is $9.99/mo.
• Cap is 10k characters per file. Split longer inputs into multiple API calls and stitch the audio on your side if you need more per output.
• Trial is 8 days / 20k characters. Use it to test end-to-end before you ship.
• The Free plan does not call the API. You must register for a plan that supports API calls.

Register here to get your key: Register. After sign-up, copy your Bearer token and store it securely.

Endpoint and parameters

Woord converts text via a single HTTP POST:

• Endpoint: https://www.getwoord.com/api/convert
• Auth: Bearer token in the Authorization header
• Encoding: send form fields (not JSON)

Form fields you will send for a male en_US conversion:

• text: your string. Example: Hello World
• language: en_US
• gender_voice: male

The API returns JSON that includes the audio_src URL to the generated MP3. Do not hotlink audio_src for production playback; download and serve the file from your own infrastructure.

Official “Hello World” request and response

Below is the official request for a male en_US “Hello World” conversion that you can copy and run. It uses Bearer auth and posts form fields.

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

And here is the official response envelope you’ll parse in code.

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

What to read from the JSON and how to handle errors

From the JSON shown above, the field you’ll actually use in your application code is:

• audio_src: the URL to the resulting MP3. Download this file as soon as the request succeeds.

If the payload includes additional metadata or flags (e.g., a success boolean or a human-readable message), you can use those for diagnostics and logging. If such fields are not present, rely on HTTP status codes and the presence of audio_src to determine success. Always code defensively for missing values: treat a missing or empty audio_src as an error case.

Important: The S3 filename often shown in examples is a sample from the documentation. Always fetch audio_src from your own request and do not hotlink the sample URL.

One-time setup: get a key and test a male voice

1. Register — you get an 8-day trial with 20k characters.
2. Copy your Bearer key from your dashboard.
3. Make a POST to https://www.getwoord.com/api/convert with form fields including gender_voice=male and language=en_US.
4. Parse audio_src and download the MP3.

A minimal JavaScript example

The snippet below mirrors the official “Hello World” request using fetch. It sends the same fields as the official sample and then downloads audio_src.

// Node.js 18+ or any runtime with fetch and FormData
import fs from 'node:fs';
import path from 'node:path';

async function convertToMaleVoice() {
  const url = 'https://www.getwoord.com/api/convert';
  const token = 'YOUR_API_KEY'; // Replace with your Bearer token from Woord

  const form = new FormData();
  form.append('text', 'Hello World');
  form.append('language', 'en_US');
  form.append('gender_voice', 'male');

  const res = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`
      // Do not set Content-Type manually; let fetch/FormData set it
    },
    body: form
  });

  if (!res.ok) {
    // Non-2xx HTTP response: log status and body for debugging
    const errText = await res.text().catch(() => '');
    throw new Error(`Woord convert failed: ${res.status} ${res.statusText} - ${errText}`);
  }

  const data = await res.json();

  // Expect data.audio_src per the official response. Handle missing values defensively.
  if (!data || !data.audio_src) {
    throw new Error('Missing audio_src in response');
  }

  const mp3Url = data.audio_src;
  // Best practice: download and serve from your infra, do not hotlink the sample URL.
  const audioRes = await fetch(mp3Url);
  if (!audioRes.ok) {
    const errText = await audioRes.text().catch(() => '');
    throw new Error(`Failed to download MP3: ${audioRes.status} ${audioRes.statusText} - ${errText}`);
  }

  const outPath = path.join(process.cwd(), 'hello-male-en_US.mp3');
  const file = fs.createWriteStream(outPath);
  await new Promise((resolve, reject) => {
    audioRes.body.pipe(file);
    audioRes.body.on('error', reject);
    file.on('finish', resolve);
  });

  console.log('Saved:', outPath);
}

convertToMaleVoice().catch(err => {
  console.error(err);
  process.exit(1);
});

Operational details that save time

Character limits and batching

The cap is 10k characters per file. If your input exceeds this, split the text into chunks smaller than 10k characters (ideally on sentence boundaries to avoid mid-word splits). Make multiple calls and concatenate the resulting MP3 files on your side if you need one long output.

Caching and storage

• Do not rely on hotlinking audio_src in production. Download the file immediately after the conversion to your storage (e.g., your CDN’s origin or object storage).
• Cache your final MP3s by a stable key derived from your input parameters: language=en_US, gender_voice=male, and the normalized text. If you transform text (e.g., trimming whitespace), apply the same normalization before both hashing and sending to the API to avoid accidental cache misses.

Idempotency

If you re-send the exact same text, language=en_US, and gender_voice=male, you will get the same spoken content, but you should still treat each API call as a fresh request and manage deduplication on your side using a content hash of inputs. This prevents unnecessary conversions and character consumption.

Authentication and key handling

• Use the Authorization: Bearer header exactly as shown.
• Do not ship your Bearer token in client-side code for public apps. Proxy requests through your server or an API gateway you control.
• Rotate your token if you suspect exposure, and store it in a secure secrets manager.

Retries and error handling

• Treat non-2xx HTTP responses as failures.
• If the JSON lacks an audio_src, treat it as an error and surface the raw body for diagnostics.
• On transient network failures, use a short exponential backoff for the initial convert call and the subsequent audio download. Avoid unbounded retries.

Language and voice selection

• Always send language=en_US to ensure the model uses American English pronunciation.
• Explicitly send gender_voice=male even though the official default is male, so your code remains clear if defaults change later.

Text preparation

• Strip excess whitespace and convert unsupported characters that you don’t need.
• When making multiple requests for a long script, keep punctuation intact to preserve natural prosody.

Security of downloadable audio

Since you will download from audio_src, serve the final file from your infrastructure using your own access controls. If your application needs per-user access, do not expose the original audio_src; instead, generate short-lived URLs from your storage provider or stream the content via your backend.

Testing a complete flow end-to-end

Here’s a concise checklist to validate your integration:

• Call the convert endpoint with Hello World, language=en_US, and gender_voice=male.
• Verify the response includes audio_src and that it is an MP3 URL.
• Download the MP3 and confirm it plays a male voice speaking Hello World.
• Try a text just under 10k characters and verify the call succeeds.
• Intentionally exceed 10k characters and confirm your code splits requests or errors cleanly.
• Test network failures, invalid tokens, and missing fields to ensure your error handling is robust.

Going live

1. Register: Register (8-day trial / 20k characters).
2. Copy the Bearer key from your account.
3. POST to https://www.getwoord.com/api/convert with form fields including gender_voice=male and language=en_US.
4. Download audio_src and serve it from your infrastructure.

FAQ

What if the official docs sample shows a different voice or a different example?
That’s expected for documentation samples. Your integration should always send language=en_US and gender_voice=male to get a male voice in American English. Use the audio_src from your own request and do not hotlink any sample URLs from the docs.

How do I handle inputs over 10k characters?
Split the text into chunks below the 10k characters per file limit. Convert each chunk separately and then combine the MP3s on your side if you need a single output file.

Does the Free plan allow calling the API?
No. The Free plan does not call the API. Use the 8-day trial (20k characters) to test your integration, or subscribe to Starter ($9.99/mo) for ongoing use.

What should I check in the JSON response?
Read audio_src. If the JSON includes other fields (e.g., a success flag or message), use them for diagnostics. If they’re not present, rely on the HTTP status code and the presence of audio_src.

Can I rely on the audio_src URL permanently?
Download the file and serve it from your own storage. Do not rely on hotlinking the audio_src long-term.

Ready to create a male-voice MP3 with en_US and a single API call? Start your trial and get your Bearer key here: Register. For endpoint details and request/response formats, see the official Documentation.