Italian Text-to-Speech API: it_IT Voice to MP3
You need to turn Italian text into an MP3 file you can stream or download, and you want an API you can call from code. By the end of this guide you’ll send a single HTTP request to Woord’s Italian text-to-speech endpoint and get back a JSON payload containing a ready-to-use MP3 URL.
What you’ll build
You will integrate an Italian text-to-speech workflow that:
- Accepts Italian input text and a voice gender.
- Uses language=it_IT to request an Italian voice.
- Receives JSON with an MP3 URL you can store and serve.
We’ll walk through the request shape, the response fields you’ll actually consume, error handling, character limits, and practical production tips like caching the returned file URL.
Account, access, and plans
Authentication uses a Bearer token. You’ll paste your key into the Authorization header for every request.
- Starter is $9.99/mo.
- Trial: 8 days / 20k characters.
- Per-file cap: 10k characters.
- The Free plan does not call the API.
If you need field-by-field references while you implement, see the Documentation.
The endpoint and required parameters
Send a POST request to /api/convert with Bearer auth and form fields (not JSON). Required fields:
- text: The content you want spoken, up to 10k characters per file.
- gender_voice: The voice gender to synthesize.
- language: Must be it_IT for Italian.
The response contains an S3 object URL created per request. Store this URL immediately after a successful response. Do not hotlink a sample MP3 from this article; generate your own with your request.
Copy‑paste curl (official)
This is the canonical request. Replace YOUR_API_KEY and the form values as needed.
Request: official convert, Italian locale
curl -X POST "https://www.getwoord.com/api/convert" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "text=Ciao mondo" \
-F "gender_voice=female" \
-F "language=it_IT"
Understand the response (official)
Here’s the official response envelope from the same convert call:
Response: official convert envelope
{
"success": true,
"message": "Your audio has been created!",
"audio_src": "https://woord-audio.s3.amazonaws.com/example.mp3"
}
How to use it:
- success: Boolean. Check this first. Only proceed if true.
- audio_src: String. The direct MP3 URL to the synthesized audio. This is what you store and play back.
If success is false or audio_src is missing, treat the call as failed. Surface a meaningful error in your app (for example: “Synthesis failed, please retry”), log the response for diagnostics, and optionally retry with backoff. If the API returns additional fields, handle them as needed in your application, but the two fields above are sufficient to ship a basic integration.
Python example: convert Italian text to an MP3 URL
The following Python snippet performs the same request as the curl above. It uses form fields and a Bearer token, and reads the audio_src field from the JSON response.
import requests
API_URL = "https://www.getwoord.com/api/convert"
API_KEY = "YOUR_API_KEY" # paste your Bearer token
payload = {
"text": "Ciao! Questo è un esempio di sintesi vocale italiana.",
"gender_voice": "female",
"language": "it_IT",
}
headers = {
"Authorization": f"Bearer {API_KEY}",
}
resp = requests.post(API_URL, data=payload, headers=headers, timeout=60)
resp.raise_for_status() # raises if HTTP status is 4xx/5xx
data = resp.json()
if not data.get("success"):
# Handle failure: log, surface error, optionally retry
raise RuntimeError(f"TTS request failed: {data}")
audio_src = data.get("audio_src")
if not audio_src:
raise RuntimeError("Missing audio_src in response")
# At this point, audio_src is your MP3 URL. Store it in your DB or object store.
print("MP3 URL:", audio_src)
Parameter notes and validation
- text: Validate client input length before sending. The cap is 10k characters per file. If the input exceeds this, split it on sentence or paragraph boundaries, synthesize each chunk separately, and stitch together on the client or playlist level.
- gender_voice: Required. Use a value your integration supports; if the request fails, inspect the error and adjust the value you pass.
- language: Must be it_IT for Italian voices. If you use a different value in tests, you’ll get a non-Italian voice. For production, fix it to it_IT.
Working with the returned MP3
The audio_src points to an S3 object issued per request. Treat it as a unique asset for that synthesis:
- Store audio_src in your database alongside the input text and any metadata (gender, locale).
- Cache strategy: if your app reuses the same text, you can deduplicate by hashing the normalized input and parameters (text + language + gender_voice) and reusing an existing audio_src when available.
- Do not assume you can reconstruct the same URL later without another API call. Persist it immediately on success.
Error handling and resilience
Always branch on success in the JSON body. If success is false or audio_src is absent:
- Log the full response for troubleshooting.
- Return a user-friendly error upstream.
- Optionally retry with exponential backoff. Avoid hot loops, and cap total retry time.
For network errors or non-2xx HTTP status codes, retry safely. Requests use form fields; ensure your HTTP client sends application/x-www-form-urlencoded or multipart form data as appropriate.
Production checklist
- Authentication: Use the Authorization: Bearer YOUR_API_KEY header in all calls. Rotate keys periodically in your secrets manager.
- Limits: Enforce the 10k characters per file cap in your code.
- Locale correctness: Lock language=it_IT in production for Italian output.
- Storage: Persist audio_src immediately after success. Associate with a deterministic content hash to avoid duplicates.
- Observability: Record request duration and whether success is true for SLOs.
- User input: Trim whitespace and normalize punctuation to reduce accidental cache misses for equivalent inputs.
- Testing: Verify both a successful path and a forced error path (e.g., deliberately omit a required field in a staging environment) to exercise your handlers.
Go live
Steps
- Register — includes an 8‑day trial with 20k characters.
- Copy your Bearer key from the dashboard.
- POST /api/convert with language=it_IT, plus text and gender_voice.
- Store audio_src from the JSON response.
Keep your key in server-side code or a protected backend, never in public client-side JavaScript.
Common pitfalls
- Sending JSON instead of form fields: This API expects form fields (text, gender_voice, language=it_IT). If you send JSON, you’ll likely get a failure.
- Wrong locale: it_IT is mandatory for Italian. Using a different code can yield a different voice or a failed request.
- Over-length input: Anything over 10k characters must be split into multiple files. Synthesize per chunk and manage playback order client-side.
- Forgetting to store audio_src: The S3 URL is created per request. Persist it so you don’t pay or wait to regenerate the same audio again.
FAQ
Does the Free plan allow API calls?
The Free plan does not call the API. Use the trial (8 days / 20k characters) or a paid plan.
How many characters can I send per request?
10k characters per file. For longer content, split it across multiple requests and combine on playback.
What’s the correct locale for Italian?
Use language=it_IT in the form fields.
Which field contains the MP3 URL?
Read audio_src from the JSON response. Always check success is true first.
Can I hotlink a sample MP3 from documentation or articles?
No. Each S3 object is issued per request. Generate your own via the API and store the returned audio_src.
Ready to speak Italian to MP3? Start your 8‑day trial and get your Bearer key now: Register. For full parameter references and more examples, keep the Documentation open while you build.
