Standard TTS API

1. Get an access token

The Standard TTS API requires an access token (64 characters). After you create an account, you can get it from the settings page.

1. Sign up for / log in to Ondoku
2. Open the access token page
3. Copy the 64-character string shown in the "Access token" field

The samples on this page assume the token is stored in the environment variable ONDOKU_TOKEN.

2. Endpoint and request

Headers

Body (JSON)

All 4 fields are required. If any of them is missing, the API returns HTTP 400.

Response

On success, the API returns application/json with the URL of the generated audio and the history ID. Fetch the MP3 binary from url.

{
  "text": "Hello, this is Ondoku.",
  "url": "https://storage.googleapis.com/ondoku3/voice/...",
  "pk": 12345,
  "share": 1
}

On failure, the API usually returns JSON {"error": "..."}. Only rate-limit responses also include reset_in.

3. Sample code

curl -X POST https://ondoku3.com/text_to_speech_api/ \
  -H "Content-Type: application/json" \
  -H "token: $ONDOKU_TOKEN" \
  -d '{
    "voice": "en-US-JennyNeural",
    "text": "Hello, this is Ondoku.",
    "speed": 1.0,
    "pitch": 0.0
  }' \
  | tee response.json
curl -L "$(jq -r .url response.json)" -o output.mp3

import os
import requests

resp = requests.post(
    "https://ondoku3.com/text_to_speech_api/",
    headers={
        "Content-Type": "application/json",
        "token": os.environ["ONDOKU_TOKEN"],
    },
    json={
        "voice": "en-US-JennyNeural",
        "text": "Hello, this is Ondoku.",
        "speed": 1.0,
        "pitch": 0.0,
    },
    timeout=60,
)
resp.raise_for_status()

data = resp.json()
mp3 = requests.get(data["url"], timeout=60).content
with open("output.mp3", "wb") as f:
    f.write(mp3)
print(f"saved: output.mp3 ({len(mp3)} bytes), pk={data['pk']}")

import { writeFile } from "node:fs/promises";

const token = process.env.ONDOKU_TOKEN!;

const res = await fetch("https://ondoku3.com/text_to_speech_api/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    token,
  },
  body: JSON.stringify({
    voice: "en-US-JennyNeural",
    text: "Hello, this is Ondoku.",
    speed: 1.0,
    pitch: 0.0,
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);

type StandardTTSResponse = {
  text: string;
  url: string;
  pk: number;
  share: number;
};

const data = (await res.json()) as StandardTTSResponse;
const audioRes = await fetch(data.url);
if (!audioRes.ok) throw new Error(`audio HTTP ${audioRes.status}: ${await audioRes.text()}`);
const buf = Buffer.from(await audioRes.arrayBuffer());
await writeFile("output.mp3", buf);
console.log(`saved: output.mp3 (${buf.byteLength} bytes), pk=${data.pk}`);

4. Errors and notice responses

5. Rate limits and quotas

• Rate limit: 30 requests per 60 seconds (per client IP address, shared across all tokens used from the same IP)
• Monthly character allowance: Each plan has a limit. You can check your usage on the settings page
• Commercial use: Allowed (see the Terms of Service)

6. Usage notes

Managing your access token

• You are responsible for a leaked access token. A third party could use up your monthly characters, so make sure the token does not end up in Git repositories, public chats, screenshots, and the like
• If you notice a leak, reissue the token immediately on the settings page
• Before building the API into a production app, we recommend issuing a token and testing connectivity with a dedicated development account

Handling of input text and generated audio

• The text you send and the generated audio are kept on the server for as long as needed to run the service (for the history feature)
• Do not send personal information, confidential information, or internal documents as is. We recommend anonymizing or abstracting them first
• You can delete your history on the history page

Retry guidelines

Concurrency

• The rate limit is 30 requests per 60 seconds (per client IP address, shared across all tokens used from the same IP). When running in parallel, aim for about 3 to 5 concurrent requests
• To avoid using up your monthly characters all at once with a large batch, estimate the workload and check your remaining characters in advance

Recommended timeouts

• Client-side HTTP timeout: 30 to 60 seconds (longer text takes longer to generate)
• The server also has an internal timeout, so waiting longer than that will not return a response

CORS (calling directly from a browser)

• This endpoint does not allow CORS. Calling it with fetch from browser JavaScript fails with a CORS error
• Proxy the request from your server (Node.js / Python / PHP, etc.)

Content policy

The following uses are prohibited:

• Generating audio for fraud, impersonation, or cloning another person's voice
• Generating content that involves illegal activity, discrimination, hate speech, or harassment of others
• Using the audio as material for inappropriate deepfakes

See the Terms of Service for details.

Copyright and commercial use of generated audio

• Audio generated through the API can be used under the same conditions as audio generated in the Web UI
• Commercial use is allowed, but check the terms before reselling or redistributing the audio (for example, selling it as audio material)

7. SLA (uptime)

Ondoku's official APIs provide the following monthly uptime as their SLA. The definitions in this section (how uptime is measured, what is excluded, and what happens if the SLA is missed) apply to both APIs.

The SLA covers uptime only, not response time.

How uptime is measured

• Uptime is measured per calendar month in Japan Standard Time (JST), from 0:00 on day 1 to 24:00 on the last day of the month
• The month is divided into 5-minute intervals. An interval counts as downtime when the API received requests during those 5 minutes and all of them returned a server error (HTTP 5xx)
• For the Advanced TTS API, both job creation (POST) and polling (GET) requests are counted. Failed speech generation (a polled job whose status is failed) does not count as downtime
• Monthly uptime = (number of intervals in the month − number of downtime intervals) ÷ number of intervals in the month

Not counted as downtime

• Scheduled maintenance announced in advance
• Outages of speech-synthesis providers or cloud infrastructure
• Causes on the client side (requests that return HTTP 4xx, such as invalid requests, rate limits, and insufficient characters)
• Events beyond our reasonable control, such as natural disasters, war, and failures of communication lines

If the SLA is missed

• For a month in which an API's monthly uptime falls below its SLA (the table above), users on a paid plan who apply by the end of the following month receive 10% of their plan's monthly character allowance for that month
• Apply through the contact form with the month in question and the email address registered to your account
• We do not issue cash refunds. This character credit is the only remedy if the SLA is missed

8. Changelog

Breaking changes (removing fields, changing types or meaning, retiring endpoints, and so on) are announced in this section 30 days before they take effect. Notable backward-compatible changes such as new fields or voices are also recorded in this section after release (no advance notice). Urgent security fixes are an exception.

9. Before contacting support

If you run into a bug or unexpected behavior, try the following first:

1. Check the error or notice: look it up in the Errors and notice responses table
2. Retry: it may be a temporary network or server-side error
3. Check your remaining characters: see your monthly usage on the settings page
4. Test with a minimal payload: check whether {"voice":"en-US-JennyNeural","text":"Test","speed":1.0,"pitch":0.0} returns 200
5. Reissue the token: if authentication errors persist, issue a new token on the settings page

If that does not solve it, contact us through the contact form. Including the following information helps us reproduce the issue:

• The request's voice / text length / speed / pitch
• The HTTP status and body of the response (mask your token)
• When it happened (with time zone)