Japanese Text-to-Speech API: ja_JP Voice to MP3
You're building an app that needs high‑quality Japanese speech audio and you want a straightforward way to turn ja_JP text into an MP3 you can host and serve. By the end of this guide you’ll have a working Japanese text‑to‑speech API call with Woord, know how to read the JSON response to extract the MP3 URL, and understand the key limits and behaviors to ship this integration to production.
What you’ll implement
The workflow is simple: authenticate with a Bearer key, POST your text and language to Woord’s convert endpoint, and receive JSON that includes a direct MP3 URL you can download. The endpoint takes form fields (not JSON), and you should read the audio_src from the response envelope.
- HTTP method: POST
- Endpoint: /api/convert
- Auth: Bearer token
- Form fields: text, gender_voice, language=ja_JP
- Result: JSON with an MP3 URL you can fetch
Important practical constraints to plan for:
- 10k characters per file: split longer input into multiple conversions.
- Trial: 8 days / 20k characters. Starter is $9.99/mo. Free cannot call convert.
- No MCP is required.
Prerequisites and account setup
Create an account and start using the API with the trial (8 days / 20k characters). Starter is $9.99/mo if you need to go beyond the trial. Free plans cannot call the convert endpoint.
- Register to get your Bearer key.
- Copy your Bearer key from the dashboard. You’ll pass it in the Authorization header.
If you need additional API details or updated parameters later, consult the Documentation.
Make a ja_JP conversion request
Use the official convert request below. It sends a POST with form fields text, gender_voice, and language=ja_JP. The response returns a JSON envelope with the MP3 URL.
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=ja_JP&speakingRate=1.00"
Python example (same request, programmatic usage)
Below is a Python example that sends the same POST request as the curl above and extracts audio_src from the JSON response. Use the exact same URL you see in the curl sample.
import os
import sys
import requests
API_KEY = os.getenv("WOORD_API_KEY", "YOUR_API_KEY") # Replace or set env var
URL = "PASTE_THE_SAME_URL_AS_IN_THE_CURL_SAMPLE" # Must be the identical /api/convert URL
# Required form fields
payload = {
"text": "これは日本語の音声合成テストです。",
"gender_voice": "female", # Use a supported value per docs
"language": "ja_JP"
}
headers = {
"Authorization": f"Bearer {API_KEY}"
}
try:
resp = requests.post(URL, headers=headers, data=payload, timeout=60)
except requests.RequestException as e:
print(f"Network error: {e}", file=sys.stderr)
sys.exit(1)
# Basic HTTP check
if resp.status_code < 200 or resp.status_code >= 300:
print(f"HTTP error: {resp.status_code} - {resp.text}", file=sys.stderr)
sys.exit(1)
data = resp.json()
# If the response includes a success flag, check it. Fallback to presence of the audio URL.
success = data.get("success", True)
if not success:
# Look for a message or error field if present
print(f"API returned success=false: {data}", file=sys.stderr)
sys.exit(1)
# audio_src is the field to read from the convert envelope
audio_src = None
# Common nesting patterns: direct field or nested under a data object; try both safely.
if isinstance(data, dict):
audio_src = data.get("audio_src")
if not audio_src and "data" in data and isinstance(data["data"], dict):
audio_src = data["data"].get("audio_src")
if not audio_src:
print(f"No audio_src found in response: {data}", file=sys.stderr)
sys.exit(1)
print("MP3 URL:", audio_src)
# In production, download the MP3 and serve it from your own origin instead of hotlinking.
# Example:
# mp3 = requests.get(audio_src, timeout=120)
# open("output.mp3", "wb").write(mp3.content)
Understand the convert response
Here’s the official convert envelope. You’ll parse this JSON and read audio_src to get the MP3 URL.
{"message":"Your audio has been created!","audio_src":"https://getwoord.s3.amazonaws.com/4273352455515882618255eaaf3c1cbdbe0.55443890.mp3","error":false}
How to use the fields:
- audio_src: The URL to the generated MP3. Treat this as a downloadable asset. Do not hotlink it; download and serve from your own infrastructure.
- Other fields: Check and use only what appears in the envelope above. If a boolean success field is present, use it to gate logic. If a message or error field appears, log it for debugging.
Error handling and missing values:
- If success is false (when provided), do not assume audio_src is valid. Surface the message to logs and retry or ask the user to adjust input.
- If audio_src is missing or empty, treat the request as failed and avoid consuming further quota on retries until you’ve investigated the root cause.
- On network timeouts or 5xx responses, implement a limited retry with backoff. Avoid re-sending the same oversized text; remember the 10k characters per file limit.
Language and voice controls
Always set language=ja_JP to synthesize Japanese. You must also provide gender_voice (for example, male or female, per the supported values). The text field is the Japanese text you want spoken.
- language: Set to ja_JP for Japanese output.
- gender_voice: Provide a supported value. If you pass an unsupported value, expect a failure; consult the Documentation for options.
- text: Your input text. Split inputs over 10k characters into multiple calls.
Production guidance and performance tips
Use these practices to keep your integration fast and predictable under load.
- Do not hotlink: The JSON returns an MP3 URL. Download it and serve from your CDN or app origin rather than embedding the S3 URL directly.
- Caching: Cache the final MP3 in your storage (e.g., object storage, CDN). If your app can deterministically recreate the same text, reuse the cached audio instead of re‑converting.
- Chunking: Respect the 10k characters per file limit. Split on sentence boundaries to avoid audible cutoffs and reassemble in your player or by concatenating audio.
- Resilience: Check for success=false (if present) and missing audio_src. Log the full response envelope to help support diagnose content issues (e.g., empty text).
- Security: Keep your Bearer key server‑side. Never expose it in client code or front‑end requests.
Go live in four steps
- Register: Start your 8‑day / 20k‑character trial here: Register.
- Copy the Bearer key: You’ll use it in the Authorization header. Free plans cannot call convert.
- POST /api/convert with language=ja_JP: Include text and gender_voice as form fields.
- Read audio_src from the convert envelope: Download the MP3 and serve it from your origin.
Convert ja_JP to MP3 → Register
Troubleshooting
- 401 or unauthorized: Verify the Authorization header is in the format “Bearer YOUR_API_KEY”. Ensure you’re not using a Free plan since it cannot call convert.
- Large inputs fail: Count characters before sending. Keep each request under 10k characters and split longer texts.
- No audio URL: If audio_src isn’t present, treat the request as failed. Inspect the response, adjust parameters (e.g., gender_voice), and retry.
- Slow downloads: Fetch the MP3 once, store it, and serve from your own CDN rather than repeatedly requesting the returned URL.
FAQ
Which language code should I use for Japanese?
Use language=ja_JP.
What plan do I need to call the convert endpoint?
Free cannot call convert. You can start with the 8‑day / 20k‑character trial. Starter is $9.99/mo.
What is the maximum size of a single conversion?
10k characters per file. Split larger content and convert in parts.
How do I get the MP3 URL from the response?
Read audio_src from the convert envelope in the JSON response. Then download the asset—do not hotlink.
Where can I find the full parameter list and any updates?
See the API Documentation.
Ready to ship Japanese TTS? Start your trial, get your Bearer key, and convert ja_JP text to MP3 now: Register.
