Kotone TTS API

Discord でログインし、発行された一時 Token を `Authorization: Bearer <token>` ヘッダに付けて呼ぶ。Token は BOT を再起動すると失効する。

仕様の機械可読版: openapi.json

ベース URL: https://kotoneapi.libertasmc.xyz

ログインの流れ

  1. ブラウザで /auth/login?redirect_uri=<戻り先> を開く → Discord の認可画面
  2. 許可すると /auth/callback を経て戻り先へ 302 され、URL のフラグメントに #token=…&token_type=Bearer&expires_in=… が付く（redirect_uri 無しなら JSON で返る。認可画面でキャンセルすると ?error=access_denied を付けて戻り先へ 302）
  3. 以後 Authorization: Bearer <token> を付けて呼ぶ

エンドポイント

GET/auth/login
Discord のログイン画面へ転送する

ブラウザでこの URL を開く。認可後 `/auth/callback` に戻る。`redirect_uri` を付けると、callback は JSON ではなくその URL へ `#token=…&token_type=Bearer&expires_in=…` を付けて 302 で戻す (許可リストにある URL だけ・完全一致)。

パラメータ場所必須
redirect_uriqueryいいえ
状態説明
302Discord の認可画面へ
400redirect_uri が許可リストに無い
GET/auth/callback
Discord からの戻り先。一時 Token を発行して返す

`/auth/login` に `redirect_uri` を付けていた場合は JSON ではなく、その URL へ `#token=…` を付けて 302 で戻す。認可画面でキャンセルされた等 (`error=`) のときは code の交換をせず、戻り先へ `?error=<code>` を付けて 302 で戻す (code は `access_denied` など OAuth2 の既知の値だけ。それ以外は `error` に潰す。戻り先が無ければ 400 の JSON)。

パラメータ場所必須
codequeryいいえ
statequeryはい
errorqueryいいえ
状態説明
200発行された Token (redirect_uri 無しのとき)
302redirect_uri へ戻す。成功なら `#token=…&token_type=Bearer&expires_in=…`、拒否なら `?error=access_denied` 等
400state が不正、または Discord が code を拒否
200 の見本
{
  "token": "string",
  "token_type": "Bearer",
  "expires_in": 0,
  "user": {
    "id": "string",
    "username": "string",
    "global_name": "string",
    "avatar": "https://…"
  }
}
POST/auth/logout🔒 要 Token
Token を失効させる
状態説明
204失効した (元から無効でも 204)
GET/info🔒 要 Token
ログイン中の利用者と、BOT も入っているサーバー一覧

利用者が参加しているサーバーのうち、この BOT が入っているものだけを返す。

状態説明
200利用者とサーバー
401Token が無い・期限切れ・Discord 側で失効
502Discord API に到達できない
200 の見本
{
  "user": {
    "id": "string",
    "username": "string",
    "global_name": "string",
    "avatar": "https://…"
  },
  "guilds": [
    {
      "id": "string",
      "name": "string",
      "icon": "https://…",
      "can_manage": true
    }
  ]
}
GET/guilds/{guild_id}/settings🔒 要 Token
サーバー設定を取得する

「サーバの管理」権限を持つサーバーだけ。BOT が入っていない・利用者が居ないサーバーは 404。

パラメータ場所必須
guild_idpathはい
状態説明
200設定と選択肢
401未ログイン
403「サーバの管理」権限が無い
404サーバーが見つからない
200 の見本
{
  "settings": {
    "default_speaker": "string",
    "max_chars": 0,
    "read_name": true,
    "read_join_leave": true,
    "use_global_dict": true,
    "auto_join": true,
    "auto_join_map": {
      "1534536028453470370": "123456789012345678"
    },
    "auto_read_map": {
      "1534536028453470370": "234567890123456789"
    },
    "unassigned_auto_join_channel_ids": [
      "string"
    ],
    "dict_edit_mode": "string",
    "dict_edit_role_id": "string"
  },
  "bans": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "options": {
    "speakers": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "bots": [
      {
        "id": "string",
        "name": "string",
        "is_main": true
      }
    ],
    "channels": [
      {
        "id": "string",
        "name": "string",
        "type": "string",
        "category": "string"
      }
    ],
    "roles": [
      {
        "id": "string",
        "name": "string",
        "color": 0
      }
    ],
    "dict_edit_modes": {}
  }
}
PATCH/guilds/{guild_id}/settings🔒 要 Token
サーバー設定を変更する (部分更新)

変えたい項目だけを JSON で送る。ID は文字列でも整数でも可。知らないキーは 400。auto_join_map / auto_read_map は全体の置き換え。検証に通らなければ何も保存せず 400 で理由を返す。

パラメータ場所必須
guild_idpathはい
状態説明
200更新後の設定 (GET と同じ形)
400入力が不正 (理由は error に)
401未ログイン
403「サーバの管理」権限が無い
404サーバーが見つからない
送れる項目
項目型説明
default_speakerstring既定の話者 ID (options.speakers から)
max_charsinteger1メッセージで読む上限 (1〜500)
read_nameboolean名前を読む
read_join_leaveboolean入退室を読む
use_global_dictbooleanグローバル辞書を使う
auto_joinboolean自動入室。true にするには auto_join_map に VC が1つは要る
auto_join_mapobject{BOT のユーザ ID: 自動入室する VC の ID}。PATCH では全体を置き換える。同じ VC を2つの BOT に割り当てられない
auto_read_mapobject{BOT のユーザ ID: 自動入室時に読み上げるチャンネルの ID}。無い BOT は参加した VC のチャットを読む。PATCH では全体を置き換える (値 null はその BOT を VC のチャットに戻す)。auto_join_map で VC を割り当てた BOT にだけ付けられる
dict_edit_modestring (admin, role, everyone)サーバー辞書を誰が編集できるか
dict_edit_role_idstringdict_edit_mode=role のときのロール。指定すると mode も role になる
200 の見本
{
  "settings": {
    "default_speaker": "string",
    "max_chars": 0,
    "read_name": true,
    "read_join_leave": true,
    "use_global_dict": true,
    "auto_join": true,
    "auto_join_map": {
      "1534536028453470370": "123456789012345678"
    },
    "auto_read_map": {
      "1534536028453470370": "234567890123456789"
    },
    "unassigned_auto_join_channel_ids": [
      "string"
    ],
    "dict_edit_mode": "string",
    "dict_edit_role_id": "string"
  },
  "bans": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "options": {
    "speakers": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "bots": [
      {
        "id": "string",
        "name": "string",
        "is_main": true
      }
    ],
    "channels": [
      {
        "id": "string",
        "name": "string",
        "type": "string",
        "category": "string"
      }
    ],
    "roles": [
      {
        "id": "string",
        "name": "string",
        "color": 0
      }
    ],
    "dict_edit_modes": {}
  }
}
PUT/guilds/{guild_id}/bans/{user_id}🔒 要 Token
読み上げBAN に追加する

その人の発言をこのサーバーで読み上げなくする。BOT は登録できない (もともと読まない)。

パラメータ場所必須
guild_idpathはい
user_idpathはい
状態説明
204登録した
400BOT を指定した等
401未ログイン
403権限が無い
404サーバーが見つからない
DELETE/guilds/{guild_id}/bans/{user_id}🔒 要 Token
読み上げBAN を解除する
パラメータ場所必須
guild_idpathはい
user_idpathはい
状態説明
204解除した (元から無くても 204)
401未ログイン
403権限が無い
404サーバーが見つからない
GET/guilds/{guild_id}/members🔒 要 Token
メンバーを名前で検索する (読み上げBAN に追加する人を探す用)

ユーザ名またはニックネームの **前方一致** (Discord の制約で部分一致は不可)。ID を渡すと ID で引く。

パラメータ場所必須
guild_idpathはい
qqueryはい
limitqueryいいえ
状態説明
200一致したメンバー
400q が空
401未ログイン
403権限が無い
404サーバーが見つからない
502Discord から取得できない
200 の見本
{
  "members": [
    {
      "id": "string",
      "name": "string",
      "username": "string",
      "avatar": "https://…",
      "bot": true
    }
  ]
}
GET/guilds/{guild_id}/dictionary🔒 要 Token
サーバー辞書の一覧

そのサーバーに居る人なら誰でも見られる。`can_edit` で自分が編集できるかが分かる (/settings の辞書編集権限に従う)。

パラメータ場所必須
guild_idpathはい
状態説明
200辞書
401未ログイン
404サーバーが見つからない
200 の見本
{
  "entries": [
    {
      "pattern": "string",
      "replacement": "string",
      "is_regex": true,
      "created_by": "string",
      "created_at": "string"
    }
  ],
  "limit": 0,
  "can_edit": true
}
POST/guilds/{guild_id}/dictionary🔒 要 Token
サーバー辞書に追加する (同じ pattern があれば上書き)

編集できるのは /settings の «辞書編集権限» を満たす人 (管理者は常に可)。

パラメータ場所必須
guild_idpathはい
状態説明
200登録された項目
400入力が不正・上限超過・危険な正規表現
401未ログイン
403編集権限が無い
404サーバーが見つからない
送れる項目
項目型説明
patternstring読み方を直したい語 (200文字まで)。同じ pattern を送ると上書き
replacementstring読み方 (200文字まで)
is_regexboolean正規表現として扱う (既定 false)。危険なパターンは 400
created_bystring登録した人のユーザ ID (応答のみ)
created_atstring登録日時 ISO 8601 (応答のみ)
200 の見本
{
  "pattern": "string",
  "replacement": "string",
  "is_regex": true,
  "created_by": "string",
  "created_at": "string"
}
DELETE/guilds/{guild_id}/dictionary🔒 要 Token
サーバー辞書から削除する
パラメータ場所必須
guild_idpathはい
patternqueryはい
状態説明
204削除した
401未ログイン
403編集権限が無い
404サーバー、または pattern が見つからない
GET/docs
この文書 (HTML)
状態説明
200HTML
GET/openapi.json
この文書 (OpenAPI JSON)
状態説明
200JSON