Brazilian Portuguese Text-to-Speech API: pt_BR Voice to MP3

You need to turn Brazilian Portuguese text into an MP3 programmatically and ship it in production. By the end of this guide you will send a pt_BR text-to-speech request to Woord, handle the JSON response, and safely serve the resulting MP3 in your app.

What you’ll build: Convert pt_BR text to an MP3 URL

Woord exposes a single text-to-speech convert endpoint that accepts form fields and returns a JSON envelope containing the MP3 URL. You will:

• Authenticate with a Bearer key.
• POST text, voice gender, and language=pt_BR.
• Read the audio_src field from the response and use it to serve audio.

If you’re new to the API, start with an 8-day trial (20k characters) via Register, then refer to the official Documentation for production hardening.

Go live in four steps

1) Create an account

Register for the 8-day / 20k characters trial here: Register.

2) Get your Bearer key

Copy your API key from the dashboard. You will send it as Authorization: Bearer YOUR_API_KEY. Note: the Free plan cannot call the convert endpoint.

3) Send a convert request for Brazilian Portuguese

Use language=pt_BR to generate Brazilian Portuguese. European Portuguese is a different language value (pt_PT).

4) Read the audio URL from the JSON

On success, parse audio_src from the JSON to get your MP3 URL.

Official convert request (pt_BR)

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

Official response envelope

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

Interpretation you’ll actually use:

• success: Boolean status flag. Check this first. If false, do not assume other fields are present.
• audio_src: The MP3 URL you will serve or download. This is the primary output of the API.
• message: Human-readable context on failures (and sometimes informational text).

Important: the S3 filename shown above belongs to the documentation sample. Your own calls will return a different audio_src. Do not hotlink the docs URL; always use the one returned to your request.

Copy-paste curl for Brazilian Portuguese (pt_BR)

This example uses form fields (not JSON). It targets Brazilian Portuguese and selects a female voice. Replace YOUR_API_KEY and the text value.

curl -X POST "https://www.getwoord.com/api/convert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "text=Olá, mundo! Este é um teste de conversão de texto em fala em português do Brasil." \
  -F "gender_voice=female" \
  -F "language=pt_BR"

Python example: send, validate, and read audio_src

The snippet below posts the same request, checks success, handles missing or unexpected fields defensively, and prints the MP3 URL.

import os
import sys
import requests

API_KEY = os.getenv("WOORD_API_KEY", "YOUR_API_KEY")
ENDPOINT = "https://www.getwoord.com/api/convert"

def convert_pt_br(text, gender="female"):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    data = {
        "text": text,
        "gender_voice": gender,
        "language": "pt_BR",
    }
    resp = requests.post(ENDPOINT, headers=headers, files=None, data=data)
    # If the API responds with JSON, decode it; otherwise raise for visibility.
    try:
        body = resp.json()
    except ValueError:
        raise RuntimeError(f"Non-JSON response (status {resp.status_code}): {resp.text[:300]}")

    # Check the success flag first.
    if not isinstance(body, dict) or not body.get("success"):
        # Read a message when present; fall back to HTTP status/message.
        msg = body.get("message") if isinstance(body, dict) else None
        raise RuntimeError(f"Convert failed: {msg or f'HTTP {resp.status_code}'}")

    audio_src = body.get("audio_src")
    if not audio_src:
        raise RuntimeError("Convert succeeded but audio_src is missing or empty.")

    return audio_src

if __name__ == "__main__":
    try:
        url = convert_pt_br("Olá! Vamos converter este texto para áudio em português do Brasil.", gender="female")
        print("MP3 URL:", url)
    except Exception as e:
        print("Error:", e, file=sys.stderr)
        sys.exit(1)

Parameters and how to choose them

• text: The content you want to synthesize. Keep each file within 10,000 characters; if your content is longer, chunk it and stitch or sequence the resulting MP3s.
• gender_voice: Select a voice gender available to your account (for example, female or male as supported in your plan).
• language: Use pt_BR for Brazilian Portuguese. Do not send pt_PT unless you want European Portuguese.

All fields are posted as form fields. Do not send JSON in the request body.

Response handling and failure modes

Woord returns a JSON envelope. Always check success first, then look for audio_src on success or message on failure. Treat missing fields defensively:

• If success is false or missing, do not attempt to use audio_src.
• If audio_src is missing on success, treat it as a failure and surface an actionable error (retry later, validate inputs, or contact support).
• Log the message when provided to aid debugging.

The docs sample shows a specific S3-style URL for audio_src. Your responses will contain different URLs. Cache or store the value you receive; do not reuse the docs URL.

Production notes: limits, retries, and caching

• Character limits: Each file is capped at 10,000 characters. For larger content, split your text into logical sections and call /api/convert for each part. Keep track of sequence order on the client or server.
• Trial and plan access: The trial provides 8 days / 20k characters. The Free plan cannot call convert. Starter is $9.99/mo. Choose a plan that fits your volume and voice requirements.
• Caching: The response includes a direct MP3 URL. Cache this URL in your database keyed by the source text, language, and voice parameters. If you use a CDN or proxy, respect the origin’s caching headers. Reuse the same MP3 when the source text and parameters are unchanged.
• Idempotency: If you need deterministic outputs for identical inputs, key your cache on the tuple (text, language, gender_voice) and avoid unnecessary re-generation.
• Retries: On transient HTTP errors, implement exponential backoff. If the JSON contains success=false, retry only when the message clearly indicates a recoverable condition.
• Timezones and timestamps: The convert response does not include timestamps; there is no timezone handling required for this API call.
• Currency and units: There are no monetary amounts or physical units in the response. Plan pricing is denominated as listed above; do not expect currency fields in API responses.
• MCP: There is no MCP layer to configure.

Common pitfalls to avoid

• Sending JSON instead of form fields. Use -F in curl or FormData/application/x-www-form-urlencoded in your client.
• Forgetting language=pt_BR. If the language code is wrong, you won’t get Brazilian Portuguese.
• Using the docs S3 URL. Always use the audio_src returned to your request.
• Exceeding the 10k characters per file cap. Pre-validate and chunk long texts.
• Calling convert from a Free plan. Upgrade or start the trial to access the endpoint.

Minimal JavaScript example (browser or Node with fetch)

This example posts the same fields and extracts audio_src. In browsers, use fetch with FormData and your Bearer token.

async function convertPtBr(text, gender = "female") {
  const url = "https://www.getwoord.com/api/convert";
  const form = new FormData();
  form.append("text", text);
  form.append("gender_voice", gender);
  form.append("language", "pt_BR");

  const res = await fetch(url, {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    },
    body: form
  });

  let body;
  try {
    body = await res.json();
  } catch (e) {
    throw new Error(`Non-JSON response (status ${res.status})`);
  }

  if (!body || body.success !== true) {
    const msg = body && body.message ? body.message : `HTTP ${res.status}`;
    throw new Error(`Convert failed: ${msg}`);
  }

  const audioSrc = body.audio_src;
  if (!audioSrc) {
    throw new Error("Convert succeeded but audio_src is missing.");
  }

  return audioSrc;
}

// Example usage:
convertPtBr("Oi! Vamos criar um MP3 em português do Brasil.")
  .then(url => console.log("MP3 URL:", url))
  .catch(err => console.error(err));

Testing and verification checklist

• Authentication: Verify the Bearer token is present and correct; 401s or success=false indicate issues.
• Language quality: Listen to short and long samples to confirm the voice and locale (pt_BR) match your requirements.
• Error handling: Simulate malformed inputs (empty text, unsupported language) and confirm your client surfaces message and avoids using a null audio_src.
• Throughput: If you batch many requests, observe the character cap per file and throttle/retry responsibly.
• Serving audio: Decide whether to stream directly from audio_src or copy the MP3 to your storage, depending on your architecture and caching policy.

FAQ

How do I request Brazilian vs. European Portuguese?
Send language=pt_BR for Brazilian Portuguese. European Portuguese uses a different value: pt_PT.

What are the limits per file and how do I handle longer texts?
Each file is capped at 10,000 characters. Split longer content into chunks and submit multiple convert calls, then sequence or merge the resulting MP3s as needed.

Can I use the Free plan to call convert?
No. The Free plan cannot call convert. Use the 8-day trial (20k characters) or a paid plan.

How do I handle failures in code?
Check success. If false or missing, read message for context, do not use audio_src, and decide whether to retry based on the error.

Is it okay to reuse the example MP3 URL from the docs?
No. The S3 filename in the docs is a sample. Your response returns a unique audio_src. Always use your own returned URL and cache it if you need to reuse the audio.

Ready to convert Brazilian Portuguese text to MP3? Start your 8-day trial and get a Bearer key now: Register. For full API details, visit the Documentation.