Advanced TTS API（Beta）

1. 概要と認証方式

Advanced TTS API は 感情表現や読み上げスタイル指定に対応した、より自然な音声合成エンドポイントです。非同期ジョブ方式で、POST してジョブ ID を受け取り → ポーリングで結果を取得します。

下記サンプルは、token ヘッダーでジョブを投入する流れです。Web UI と同じセッション認証で利用する場合は、ログイン済み cookie と X-CSRFToken を送信してください。

2. エンドポイント・リクエスト仕様

ヘッダー

ボディ（JSON）

3. サンプルコード（ジョブ送信 → ポーリング）

# 1) TTS ジョブを投入
JOB=$(curl -s \
  -X POST https://ondoku3.com/api/advanced-tts/ \
  -H "Content-Type: application/json" \
  -H "token: $ONDOKU_TOKEN" \
  -d '{"text":"こんにちは、音読さんです。","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) ジョブ完了までポーリング
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) 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) ジョブを投入
res = requests.post(
    "https://ondoku3.com/api/advanced-tts/",
    headers={
        "Content-Type": "application/json",
        "token": TOKEN,
    },
    json={
        "text": "こんにちは、音読さんです。",
        "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) ポーリング
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) 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) ジョブを投入
const submit = await fetch("https://ondoku3.com/api/advanced-tts/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    token: TOKEN,
  },
  body: JSON.stringify({
    text: "こんにちは、音読さんです。",
    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) ポーリング
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) 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. レスポンス例

POST レスポンス（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 ポーリング（処理中）:

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

GET ポーリング（成功時）:

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

GET ポーリング（失敗時）:

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

5. 音声リスト（25 種類）

Advanced TTS API の voice パラメータに指定できる音声名 25 種類。各音声のサンプルは 音声サンプル記事で試聴できます。

女性（12 音声）

男性（13 音声）

6. エラー・案内レスポンス

エラーは JSON の code（エラーコード）と error（メッセージ）で返ります（403 の CSRF エラーと 405 を除く）。HTTP ステータスだけでなく code を見て処理してください。ジョブ投入後の失敗は、ポーリング結果の status=failed で返ります。Web UI では code に応じて案内音声を再生しますが、API レスポンス自体に案内音声 URL は含まれません。

ジョブ作成 POST /api/advanced-tts/

ポーリング GET /api/advanced-tts/jobs/{job_id}/

ジョブの状態と失敗時の code

status は pending（処理待ち）→ running（処理中）→ succeeded（完了）または failed（失敗）と進みます。failed の時の code は次のとおりです。音声生成の処理から下表以外の code が返ることもあるため、知らない code も失敗として扱ってください。

7. 文字数上限・レート制限

1 リクエストの文字数上限

補足: Web UI の入力欄は、有料プランでも既定では 1,000 文字までの表示です（Beta 設定の文字数拡張で 3,000 文字まで広がります）。API はこの設定に関係なく、有料プランなら 3,000 文字まで受け付けます。

レート制限

現在適用している制限: ジョブ作成 POST /api/advanced-tts/ は、接続元 IP ごとに 60 秒あたり 10 回までです（同じ IP から複数のトークンを使っても共有）。超えると HTTP 429 の rate_limited を返し、retry_after と Retry-After ヘッダーに待つ秒数が入ります。

このほかに、Advanced TTS 専用のレート制限は、現在 shadow mode で観測中です。この専用制限ではまだリクエストを遮断せず、超過しても 429 は返しません。正式適用後は、下記の値を超えた場合に rate_limited の JSON と Retry-After ヘッダーを返す予定です。

既存の文字数不足は quota_exceeded の JSON で返ります。現行の汎用レート制限に当たった場合は rate_limited の JSON で返ります。Web UI では案内音声を再生しますが、API クライアントは HTTP ステータスだけでなく JSON の code を見て処理してください。

429 のレスポンス例:

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

8. 使用上の注意事項

認証情報の管理

• スクリプトから利用する場合は token ヘッダーを推奨します。token 認証時は CSRF トークン不要です
• Web UI と同じログインセッション cookie + CSRF トークンでも利用できますが、セッション cookie の漏洩はアカウント全体の乗っ取りに繋がります
• 本番アカウントを直接スクリプトに渡さず、専用の開発用アカウントを用意することを強く推奨します
• セッション認証でセッションが切れた場合は再ログインが必要です（リクエストは 403 で失敗）

入力テキスト・生成音声の取り扱い

• 送信したテキストと生成された音声は、サービス運営上必要な期間サーバー側に保持されます（履歴機能のため）
• 個人情報・機密情報・社外秘の文書をそのまま送信しないでください。送信前に匿名化・抽象化することを推奨します
• 履歴は 履歴ページ から削除できます

リトライ指針

ポーリング推奨間隔

• POST レスポンスの min_poll_after_ms を最低の待機時間として尊重してください
• 処理中レスポンスに poll_after_ms が含まれる場合は、その値を次回ポーリングまでの最低待機時間として尊重してください
• poll_after_ms がない場合は 3 〜 5 秒間隔でポーリングしてください。短すぎるとレート制限に当たる可能性があります

同時実行・並列度

• 同じユーザーで同時 2 〜 3 ジョブ程度に抑えることを推奨。それ以上の並列はサーバー側で順次処理される可能性があります
• 大量バッチ処理には不向きです（標準 TTS API の方が向いています）

タイムアウト推奨値

• POST（ジョブ投入）: 30 秒程度
• GET（ポーリング）: 10 秒程度
• 音声生成の総時間: 短文 30 秒程度、長文（1000 文字超）で 2 〜 3 分かかることがあります

音声ファイル URL の有効期限

• レスポンスの url は署名付き URL（時限）です。取得後は速やかにダウンロード・保存してください
• 長期保管が必要な場合は、ダウンロードしたバイナリを自分側で保存してください

CORS（ブラウザから直接叩く場合）

• このエンドポイントは 同一オリジン（ondoku3.com）からの利用を想定しています。他オリジンからの呼び出しは CORS / CSRF で失敗します
• サーバー側からプロキシしてください

コンテンツポリシー

以下の用途での利用を禁止します:

• 詐欺・なりすまし・他者の声の複製を目的とした音声生成
• 違法行為・差別・ヘイトスピーチ・他者への嫌がらせを含むコンテンツの生成
• 不適切なディープフェイクの素材として利用すること
• tone / 読み上げスタイル指定を用いた特定個人の人格・声色の模倣

詳細は 利用規約 を確認してください。

生成音声の著作権・商用利用

• API 経由で生成された音声も、Web UI で生成した音声と同じ条件で利用できます
• 商用利用は可能ですが、音声を再販・二次配布する形態（音声素材として販売する等）は規約を確認してください

9. SLA（稼働率）

Advanced TTS API（Beta）は、月間稼働率 98.0% を SLA として提供します。ジョブの作成（POST）とポーリング（GET）の両方のリクエストを数え、音声生成の失敗（ポーリング結果のジョブの status が failed）は停止に数えません。

稼働率の数え方・停止に含めないもの・SLA を下回った場合の扱いは両 API に共通で、標準 TTS API の SLA 節 を正本とします。SLA の対象は稼働率のみで、応答時間は含みません。

10. 変更履歴

互換性を壊す変更（項目の削除・型や意味の変更・エンドポイントの廃止など）は、実施の 30 日前にこの節で告知します。項目や声の追加など互換を保つ主な変更も、実施後にこの節に記録します（事前告知はしません）。緊急のセキュリティ対応は例外です。

11. 問い合わせ前に

不具合や予期しない挙動を確認したら、まず以下を試してください:

1. エラー・案内内容を確認: エラー・案内レスポンス 表で対応を確認
2. Web UI で再現するか確認: Advanced TTS ページ で同じテキスト・voice・tone を試す
3. CSRF / Cookie を確認: 403 が返る場合は再ログインしてセッションを取り直す
4. 残文字数を確認: 設定ページ で月間文字数の消費量を確認
5. 最小ペイロードで疎通テスト: {"text":"これは疎通テストです。","voice":"Ruby"}（text は 10 文字以上） で 202 が返るか
6. seed を変えて再試行: 生成失敗は seed 依存の可能性があるため、seed を変えるか省略

上記で解消しない場合は お問い合わせ からご連絡ください。再現に必要な以下の情報を添えていただけるとスムーズです:

• リクエストの voice / text の長さ / tone / model / seed
• POST レスポンスの job_id と HTTP ステータス
• ポーリング結果（status と code / error）
• 発生日時（タイムゾーン付き）