Advanced TTS API (Beta)

1. Overview and authentication

The Advanced TTS API is a more natural-sounding speech synthesis endpoint that supports emotional expression and speaking-style control. It uses asynchronous jobs: you POST a request to get a job ID, then poll for the result.

The samples below submit a job with the token header. To use the same session authentication as the Web UI, send the logged-in cookie and X-CSRFToken.

2. Endpoints and request

Headers

Body (JSON)

3. Sample code (submit a job → poll)

# 1) Submit a TTS job
JOB=$(curl -s \
  -X POST https://ondoku3.com/api/advanced-tts/ \
  -H "Content-Type: application/json" \
  -H "token: $ONDOKU_TOKEN" \
  -d '{"text":"Hello, this is Ondoku.","voice":"Ruby","tone":"warm and friendly"}')
JOB_ID=$(echo "$JOB" | jq -r .job_id)
JOB_TOKEN=$(echo "$JOB" | jq -r .job_token)
sleep "$(echo "$JOB" | jq -r '.min_poll_after_ms / 1000')"

# 2) Poll until the job finishes
while :; do
  R=$(curl -s \
    -H "X-Job-Token: ${JOB_TOKEN}" \
    "https://ondoku3.com/api/advanced-tts/jobs/${JOB_ID}/")
  STATUS=$(echo "$R" | jq -r .status)
  echo "status: $STATUS"
  [ "$STATUS" = "succeeded" ] && break
  [ "$STATUS" = "failed" ] && { echo "$R"; exit 1; }
  sleep "$(echo "$R" | jq -r '(.poll_after_ms // 3000) / 1000')"
done

# 3) Download the MP3
URL=$(echo "$R" | jq -r .url)
curl -L "$URL" -o output.mp3

import os
import time
import requests

TOKEN = os.environ["ONDOKU_TOKEN"]

# 1) Submit a job
res = requests.post(
    "https://ondoku3.com/api/advanced-tts/",
    headers={
        "Content-Type": "application/json",
        "token": TOKEN,
    },
    json={
        "text": "Hello, this is Ondoku.",
        "voice": "Ruby",
        "tone": "warm and friendly",
    },
    timeout=30,
)
res.raise_for_status()
job = res.json()
job_id, job_token = job["job_id"], job["job_token"]
time.sleep(job["min_poll_after_ms"] / 1000)

# 2) Poll
while True:
    r = requests.get(
        f"https://ondoku3.com/api/advanced-tts/jobs/{job_id}/",
        headers={"X-Job-Token": job_token},
        timeout=10,
    ).json()
    print("status:", r["status"])
    if r["status"] == "succeeded":
        break
    if r["status"] == "failed":
        raise RuntimeError(r)
    time.sleep(r.get("poll_after_ms", 3000) / 1000)

# 3) Download the MP3
mp3 = requests.get(r["url"], timeout=60).content
with open("output.mp3", "wb") as f:
    f.write(mp3)
print(f"saved: output.mp3 ({len(mp3)} bytes)")

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

const TOKEN = process.env.ONDOKU_TOKEN!;

// 1) Submit a job
const submit = await fetch("https://ondoku3.com/api/advanced-tts/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    token: TOKEN,
  },
  body: JSON.stringify({
    text: "Hello, this is Ondoku.",
    voice: "Ruby",
    tone: "warm and friendly",
  }),
});
type AdvancedTTSJobResponse = {
  job_id: string;
  job_token: string;
  status: "pending" | "running" | "succeeded" | "failed";
  min_poll_after_ms: number;
  poll_url: string;
};

type AdvancedTTSPollResponse = {
  job_id: string;
  status: "pending" | "running" | "succeeded" | "failed";
  poll_after_ms?: number;
  url?: string;
  pk?: number;
  seed?: number;
  code?: string;
  error?: string;
};

const job = (await submit.json()) as AdvancedTTSJobResponse;

// 2) Poll
let result: AdvancedTTSPollResponse;
await new Promise((resolve) => setTimeout(resolve, job.min_poll_after_ms));
while (true) {
  const r = await fetch(`https://ondoku3.com/api/advanced-tts/jobs/${job.job_id}/`, {
    headers: { "X-Job-Token": job.job_token },
  }).then((res) => res.json() as Promise);
  console.log("status:", r.status);
  if (r.status === "succeeded") { result = r; break; }
  if (r.status === "failed") throw new Error(JSON.stringify(r));
  await new Promise((resolve) => setTimeout(resolve, r.poll_after_ms ?? 3000));
}

// 3) Download the MP3
if (!result.url) throw new Error("audio URL is missing");
const mp3 = Buffer.from(await (await fetch(result.url)).arrayBuffer());
await writeFile("output.mp3", mp3);
console.log(`saved: output.mp3 (${mp3.byteLength} bytes)`);

4. Response examples

POST response (202 Accepted):

{
  "job_id": "YOUR_JOB_ID",
  "job_token": "YOUR_JOB_TOKEN",
  "status": "pending",
  "min_poll_after_ms": 4550,
  "poll_url": "/api/advanced-tts/jobs/YOUR_JOB_ID/"
}

GET polling (in progress):

{
  "job_id": "YOUR_JOB_ID",
  "status": "pending",
  "poll_after_ms": 1000
}

GET polling (succeeded):

{
  "job_id": "YOUR_JOB_ID",
  "status": "succeeded",
  "url": "https://storage.googleapis.com/ondoku3/voice/...",
  "pk": 12345,
  "seed": 123456789
}

GET polling (failed):

{
  "job_id": "YOUR_JOB_ID",
  "status": "failed",
  "code": "internal_error",
  "error": "内部サーバーエラーが発生しました"
}

5. Voice list (25 voices)

The 25 voice names you can specify in the voice parameter of the Advanced TTS API. You can listen to each voice in the voice sample article.

Female (12 voices)

Male (13 voices)

6. Errors and notice responses

Errors are returned as JSON with code (error code) and error (message), except for 403 CSRF errors and 405. Branch on code, not only on the HTTP status; the error message is currently in Japanese. Failures after a job is submitted are returned as status=failed in the polling result. The Web UI plays a notice audio depending on code, but API responses do not include a notice audio URL.

Job creation POST /api/advanced-tts/

Polling GET /api/advanced-tts/jobs/{job_id}/

Job status and failure codes

status moves from pending (waiting) → running (processing) → succeeded (done) or failed (failed). When it is failed, code is one of the following. Speech generation may also return codes not listed here, so treat unknown codes as failures too.

7. Character limits and rate limits

Characters per request

Note: Even on paid plans, the Web UI input field shows up to 1,000 characters by default (the Beta setting for longer text extends it to 3,000 characters). Regardless of that setting, the API accepts up to 3,000 characters on paid plans.

Rate limits

Currently enforced: Job creation POST /api/advanced-tts/ is limited to 10 requests per 60 seconds per client IP address (shared across all tokens used from the same IP). When you exceed it, the API returns HTTP 429 with rate_limited, and retry_after and the Retry-After header contain the number of seconds to wait.

In addition, dedicated rate limits for Advanced TTS are currently being observed in shadow mode. These dedicated limits do not block requests yet and do not return 429 when exceeded. Once enforced, exceeding the values below will return rate_limited JSON and a Retry-After header.

Insufficient characters are returned as quota_exceeded JSON. Hitting the current general rate limit returns rate_limited JSON. The Web UI plays a notice audio, but API clients should branch on code in the JSON, not only on the HTTP status.

Example 429 response (the error message is returned in Japanese):

{
  "code": "rate_limited",
  "error": "レート制限を超えました。しばらく経ってから再試行してください。",
  "retry_after": 55
}

8. Usage notes

Managing credentials

• For scripts, we recommend the token header. No CSRF token is needed with token authentication
• You can also use the same logged-in session cookie and CSRF token as the Web UI, but a leaked session cookie can lead to a takeover of the whole account
• We strongly recommend creating a dedicated development account instead of passing your production account to scripts
• With session authentication, you need to log in again when the session expires (requests fail with 403)

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

Recommended polling interval

• Treat min_poll_after_ms in the POST response as the minimum wait
• When an in-progress response includes poll_after_ms, treat it as the minimum wait before the next poll
• If there is no poll_after_ms, poll every 3 to 5 seconds. Polling too often may hit the rate limit

Concurrency

• We recommend keeping it to about 2 to 3 concurrent jobs per user. More parallel jobs may be processed one after another on the server
• Not suited to large batch processing (the Standard TTS API is a better fit)

Recommended timeouts

• POST (job submission): about 30 seconds
• GET (polling): about 10 seconds
• Total generation time: about 30 seconds for short text; long text (over 1000 characters) can take 2 to 3 minutes

Expiry of the audio file URL

• url in the response is a signed, time-limited URL. Download and save the file promptly
• If you need to keep the audio long term, store the downloaded binary on your side

CORS (calling directly from a browser)

• This endpoint is intended for same-origin use (ondoku3.com). Calls from other origins fail because of CORS / CSRF
• Proxy the request from your server

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
• Imitating a specific person's personality or voice with tone / speaking-style instructions

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)

9. SLA (uptime)

The Advanced TTS API (Beta) provides 98.0% monthly uptime as its SLA. Both job creation (POST) and polling (GET) requests are counted, and failed speech generation (a polled job whose status is failed) does not count as downtime.

How uptime is measured, what is excluded, and what happens if the SLA is missed are common to both APIs, and the SLA section of the Standard TTS API is the authoritative definition. The SLA covers uptime only, not response time.

10. 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.

11. 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. Check whether it reproduces in the Web UI: try the same text, voice, and tone on the Advanced TTS page
3. Check CSRF / cookies: if you get 403, log in again to get a new session
4. Check your remaining characters: see your monthly usage on the settings page
5. Test with a minimal payload: check whether {"text":"This is a connectivity test.","voice":"Ruby"} (text must be at least 10 characters) returns 202
6. Retry with a different seed: a failed generation may depend on the seed, so change the seed or omit it

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 / tone / model / seed
• The job_id and HTTP status of the POST response
• The polling result (status and code / error)
• When it happened (with time zone)