Spanish Text-to-Speech API: es_ES Voice to MP3

Need to turn Spanish (Spain) text into an MP3 you can play in your app? By the end of this guide, you’ll POST a short Spanish string to Woord’s text-to-speech API and get back an audio_src you can download as an MP3, using the es_ES voice.

What you’ll build

You’ll send a form-encoded POST to Woord’s convert endpoint with language=es_ES and your text input. On success, the API returns a JSON envelope containing an audio_src you can fetch as an MP3. You can run this from curl or your own Python/JavaScript code.

When to use es_ES (Spanish, Spain)

Use es_ES for European Spanish. In the Woord voice picker, this corresponds to Enrique or Conchita. If you need regional variants, Mexican Spanish is es_MX and U.S. Spanish is es_US. In this tutorial we focus on es_ES.

Auth, plans, and limits you should know first

• Auth: Bearer token in the Authorization header.
• Trial: 8 days / 20k characters. Start here to test the API quickly: Register.
• Starter: $9.99/mo.
• Per-file cap: 10k characters per file. Split longer inputs into multiple requests.
• The Free plan does not call the API.

Endpoint and request shape

Woord’s Spanish TTS uses the same convert envelope as the English samples. It’s a form POST (not JSON) to:

POST https://www.getwoord.com/api/convert

Set your Authorization header to Bearer YOUR_API_KEY and include the official form fields. For Spanish (Spain), make sure language=es_ES.

Copy-paste curl

The following request uses the official convert fields. Update the Bearer token, set language to es_ES, and provide your Spanish text. This is a form-encoded POST (not JSON).

Run it as-is (with your key) to verify connectivity, then adjust the payload to your use case.

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

What the API returns

Below is the official convert response sample (same envelope as the en_US posts). The sample may contain a specific audio URL used for documentation. Do not hotlink that URL. Always read audio_src from your own response and download that.

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

How to use the fields you care about:

• success: Boolean. Check this first before using any other field.
• audio_src: A URL you can download to get the MP3 file. Fetch and store it on your side; do not hotlink the sample link from the docs.
• Other fields: Treat them as informational unless your workflow needs them. Handle any missing or null fields defensively.

If success is false, do not assume any other field exists. Log or display enough context to debug, and retry only after you’ve adjusted the request parameters or input size (e.g., text length over the 10k characters per file cap).

A minimal Python example

This Python snippet posts the same request as the curl above. Use the exact same form field names from the official sample and set language=es_ES. Replace YOUR_API_KEY and provide your Spanish text. After the call, it reads audio_src and downloads the MP3.

import os
import requests

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

# IMPORTANT:
# - Use the exact same form fields as in the curl sample above.
# - Set language to "es_ES".
# - Provide your Spanish text (<= 10k characters per file).
form = {
    # Copy the official convert fields from the curl sample and update values as needed.
    # Example adjustments for Spanish (Spain):
    # "language": "es_ES",
    # "text": "Hola, este es un ejemplo en español de España.",
    # Keep any other required fields exactly as shown in the official request.
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

resp = requests.post(url, data=form, headers=headers, timeout=60)
resp.raise_for_status()
data = resp.json()

if not data.get("success"):
    raise SystemExit("Conversion failed. Check your input fields, language=es_ES, and character limits.")

audio_src = data.get("audio_src")
if not audio_src:
    raise SystemExit("No audio_src in the response. Ensure you used the official form fields and language=es_ES.")

# Download and save the MP3 locally (do not hotlink the docs sample).
mp3 = requests.get(audio_src, timeout=120)
mp3.raise_for_status()
out_file = "woord_es_ES.mp3"
with open(out_file, "wb") as f:
    f.write(mp3.content)
print(f"Saved MP3 to {out_file}")

Input quality, length, and splitting strategy

The per-file cap is 10k characters. If your input exceeds this, split on sentence boundaries or paragraph breaks. Preserve punctuation for more natural prosody. Submit each chunk in sequence and store the resulting audio files with an order index so you can join them client-side if needed.

Downloading and storing the MP3

After you POST, read audio_src from your own response and immediately download the file. Do not embed or hotlink the audio_src from the documentation sample. For production apps, store the MP3 in your own storage and serve it via your CDN. This avoids repeated downloads and reduces latency for end users.

Error handling and retries

• Check success. If false, do not assume any other fields exist.
• Validate character length. If you’re close to 10k, measure the exact character count and split before sending.
• Handle timeouts by retrying with backoff. Do not retry blindly if you keep hitting validation errors.
• Log the full request shape (excluding secrets) so you can reproduce issues quickly.

Regional variants and voice notes

For Spanish (Spain), set language=es_ES. In the voice picker, Enrique and Conchita are the es_ES voices. If your users expect Mexican or U.S. Spanish, use es_MX or es_US. Ensure your app’s copy makes the regional choice explicit to avoid mismatched expectations.

Going live

Steps

1. Register (8-day trial / 20k characters): Register.
2. Copy the Bearer key from your dashboard.
3. POST the official convert form fields with language=es_ES.
4. Download audio_src from your own response and store the MP3.

Operational tips that save time

• Cache your rendered outputs. If the same Spanish text is reused (e.g., onboarding prompts), save the MP3 and reuse it.
• Do not hotlink the documentation audio URL. Always fetch from your own audio_src value.
• Plan for content updates. If your Spanish copy changes, regenerate and version your files so clients don’t serve stale audio.
• Monitor character usage across environments (local, staging, prod) so you don’t fragment limits across builds.

Troubleshooting checklist

• 401 or auth issues: Confirm Authorization: Bearer YOUR_API_KEY is set and the key is valid.
• Validation errors: Ensure you used the exact convert form fields and language=es_ES for Spanish (Spain).
• Long inputs: If text is over 10k characters, split and send multiple files.
• Empty audio_src: Only use audio_src from your own successful response. If missing, re-check required fields and language.

FAQ

Which language code should I use for Spain’s Spanish?
Use language=es_ES. Mexican Spanish is es_MX and U.S. Spanish is es_US.

Can I test the API without paying?
Yes. The trial is 8 days with 20k characters. Start here: Register. The Free plan does not call the API.

What’s the max input size per request?
10k characters per file. Split longer text and send multiple requests.

Is the request JSON or form data?
Form fields (not JSON) posted to https://www.getwoord.com/api/convert with Bearer authorization.

Can I hotlink the audio URL from the documentation?
No. Always read audio_src from your own response and download that file.

Ready to generate Spanish (Spain) MP3s from your own code? Start your 8-day trial, grab your Bearer key, and ship your first es_ES conversion: Register. For full parameter details and the official convert envelope, see the Documentation.