Developers

公開API

UX-TTS-Bot の稼働状況ページと同じデータを、JSON で取得できる公開APIです。認証不要で誰でも利用できます。自分のダッシュボードやステータスモニターへの組み込みなどにご活用ください。

利用にあたって

認証不要 — APIキーやトークンなしで誰でも呼び出せます。
CORS許可 — すべてのオリジンから access-control-allow-origin: * でアクセスできます。
キャッシュ — レスポンスはエッジで約5分（300秒）キャッシュされます。最新の値が数分遅れて反映されることがあります。
ポーリング間隔 — キャッシュの都合上、5分間隔でのポーリングで十分です。過度なポーリングは控えてください。
バージョニング — 現在の仕様は v1 です。今後仕様が拡張される可能性はありますが、v1 では既存フィールドの後方互換を維持する方針です。破壊的な変更が必要な場合は新しいバージョンパス（例: /api/v2/...）を追加します。

GET /api/v1/status

サービス全体の稼働状況（レイテンシ・リクエスト数・キャッシュヒット率・エンジン別利用割合など）を返します。稼働状況ページが表示している内容と同じデータです。

リクエスト例

curl https://tts-promo.ux-labs.jp/api/v1/status

レスポンス例

{
  "updatedAt": "2026-07-21T12:00:00.000Z",
  "status": "ok",
  "latency": { "avgMs": 150, "p95Ms": 210 },
  "requests": { "last24h": 1800, "last1h": 120 },
  "cacheHitRate": 61.1,
  "engineShare": { "voicevoxPercent": 83.3, "openJTalkPercent": 16.7 },
  "series": {
    "requestsHourly": [{ "start": "2026-07-21T11:00:00.000Z", "count": 90 }],
    "latencyHourly": [{ "start": "2026-07-21T11:00:00.000Z", "avg": 140 }]
  },
  "components": [{ "name": "音声合成エンジン", "ok": true }],
  "guildCount": 42
}

フィールド一覧

フィールド	型	説明
`updatedAt`	string \| null	データの最終更新日時（ISO 8601）。取得できなかった場合は null。
`status`	string	`ok` \| `degraded` \| `unknown`。unknown は元データを取得できなかった場合のフェイルセーフ値。
`latency.avgMs`	number	平均レイテンシ（ミリ秒）。
`latency.p95Ms`	number	p95 レイテンシ（ミリ秒）。
`requests.last24h`	number	直近24時間のリクエスト数。
`requests.last1h`	number	直近1時間のリクエスト数。
`cacheHitRate`	number	キャッシュヒット率（%）。
`engineShare.voicevoxPercent`	number	VOICEVOX が使われた割合（%）。
`engineShare.openJTalkPercent`	number	OpenJTalk が使われた割合（%）。
`series.requestsHourly`	array	1時間ごとのリクエスト数の推移。各要素は `{ start, count }`。
`series.latencyHourly`	array	1時間ごとの平均レイテンシの推移。各要素は `{ start, avg }`。
`components`	array	各コンポーネントの稼働状況。各要素は `{ name, ok }`。
`guildCount`	number \| null	導入サーバー数。取得できなかった場合は null。

GET /api/v1/stats

導入サーバー数のみを軽量に取得したい場合のエンドポイントです。内部でキャッシュされた値を返すため、/api/v1/status より高速に応答します。

リクエスト例

curl https://tts-promo.ux-labs.jp/api/v1/stats

レスポンス例（成功時）

{
  "guild_count": 42,
  "source": "origin",
  "updated_at": "2026-07-21T12:00:00.000Z"
}

フィールド一覧

フィールド	型	説明
`guild_count`	number \| null	導入サーバー数。
`source`	string	値の取得元。`origin`（最新取得）、`cache`（キャッシュ）、`cache_fallback`（取得失敗時の古いキャッシュ）のいずれか。
`updated_at`	string \| null	値の最終更新日時（ISO 8601）。

エラー時のレスポンス（503）

導入サーバー数を取得できず、キャッシュも存在しない場合は HTTP 503 で以下の形式のエラーを返します。

{
  "error": "guild_count_unavailable",
  "guild_count": null
}

旧パスについて

従来から提供している /api/status と /api/stats も、これまで通りそのまま利用できます。新規に組み込む場合は、バージョンが明示された /api/v1/status ・ /api/v1/stats のご利用をおすすめします。