# VocalX API (エージェント向け説明)

VocalX は Discord のボイスチャンネル (VC) でテキストを読み上げる Bot です。
この API で、**キーの持ち主が参加している VC で文章を読み上げさせる**ことと、情報の取得・設定変更ができます。

## 使い方の要点
- ベース URL: `https://vocalx.nexxnet.org`
- 認証: すべてのリクエストに `Authorization: Bearer <YOUR_API_KEY>` を付ける (`X-API-Key` ヘッダーでも可)。
- 形式: リクエストもレスポンスも JSON (`Content-Type: application/json`)。
- 成功は `{"ok": true, ...}`、失敗は `{"ok": false, "error": "...", "code": "..."}`。
- 読み上げは「キーの持ち主が今その VC に参加していること」が条件。他人の VC には送れない。
- キーの権限 (スコープ): `bot` = 操作 API / `admin` = 管理 API (サービス管理者のキーのみ)。
- OpenAPI 定義: `https://vocalx.nexxnet.org/api/v1/openapi.json`

## 基本の流れ
1. `GET /api/v1/bot/session` で、自分が参加している VC (VocalX 接続中) を確認する。
2. `in_vc` が true なら `POST /api/v1/bot/say` に `{"text": "..."}` を送る。
3. `code` が `not_in_vc` なら「VocalX のいる VC に参加してから再試行して」と利用者に伝える。

## エンドポイント

### GET /api/v1/bot/me  (スコープ: bot)
キーの持ち主と権限を確認する。
接続テストにも使えます。このキーに付いているスコープ、管理者かどうか、現在のプランを返します。

```bash
curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/bot/me" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```
レスポンス例:
```json
{
  "ok": true,
  "user_id": "123456789012345678",
  "is_admin": false,
  "scopes": [
    "tts",
    "bot"
  ],
  "plan": "free",
  "limits": {
    "say_per_minute": 20,
    "max_text_length": 200
  }
}
```

### GET /api/v1/bot/session  (スコープ: bot)
自分が今参加している VC (VocalX が接続中のもの) を取得する。
キーの持ち主が参加していて、かつ VocalX が接続している VC を返します。空の `sessions` は「どの VocalX の VC にも居ない」ことを表します。情報は十数秒おきに更新されます。

```bash
curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/bot/session" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```
レスポンス例:
```json
{
  "ok": true,
  "in_vc": true,
  "sessions": [
    {
      "guild_id": "111111111111111111",
      "guild_name": "テストサーバー",
      "vc_channel_id": "222222222222222222",
      "vc_channel_name": "雑談",
      "text_channel_id": "333333333333333333",
      "text_channel_name": "聞き専",
      "instance_id": "sub",
      "bot_name": "VocalX 2",
      "humans": 3
    }
  ]
}
```

### POST /api/v1/bot/say  (スコープ: bot)
自分が参加している VC で、指定した文章を読み上げさせる。
キーの持ち主が **今その VC に参加していること** が条件です (Bot も実行時に再確認します)。参加中の VC が 1 つだけなら guild_id などは省略できます。話者・話速はキーの持ち主のプランで許される範囲に自動で調整され、辞書・絵文字設定などは通常の読み上げと同じです。他の人の VC には送れません。

パラメータ:
- `text` (body, string, 必須): 読み上げる文章 (最大 200 文字。プランの上限でさらに短くなることがある)
- `guild_id` (body, string, 任意): サーバー ID。参加中の VC が複数あるときに指定
- `vc_channel_id` (body, string, 任意): VC の ID。参加中の VC が複数あるときに指定
- `speaker` (body, string, 任意): 話者 ID または名前 (省略時は自分の設定 → サーバーの設定の順)
- `speed` (body, number, 任意): 話速 (プランの範囲に自動で調整される)

```bash
curl -sS -X POST "https://vocalx.nexxnet.org/api/v1/bot/say" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"text": "こんにちは、テストです", "speed": 1.0}'
```
レスポンス例:
```json
{
  "ok": true,
  "message": "読み上げました",
  "guild_id": "111111111111111111",
  "vc_channel_id": "222222222222222222",
  "instance_id": "sub"
}
```

### GET /api/v1/bot/settings  (スコープ: bot)
自分の読み上げ設定を取得する。
Web の「読み上げ設定」と同じ内容です。`speaker` が null なら「サーバーの設定に従う」です。

```bash
curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/bot/settings" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```
レスポンス例:
```json
{
  "ok": true,
  "speaker": {
    "id": 3,
    "name": "ずんだもん"
  },
  "speed": null,
  "callname": "",
  "plan": "free",
  "allowed_speaker_ids": [
    3,
    2
  ],
  "speed_range": [
    1.0,
    1.0
  ]
}
```

### PATCH /api/v1/bot/settings  (スコープ: bot)
自分の読み上げ設定を変更する。
指定した項目だけ変更します。null を渡すとその項目を初期化します (サーバーの設定に従う)。プランで許されない話者・話速は 400 で拒否されます。

パラメータ:
- `speaker` (body, string|null, 任意): 話者 ID または名前
- `speed` (body, number|null, 任意): 話速
- `callname` (body, string|null, 任意): 呼び名 (最大 20 文字)

```bash
curl -sS -X PATCH "https://vocalx.nexxnet.org/api/v1/bot/settings" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"speaker": "ずんだもん", "speed": 1.0}'
```
レスポンス例:
```json
{
  "ok": true,
  "changed": [
    "speaker",
    "speed"
  ]
}
```

### GET /api/v1/admin/overview  (スコープ: admin)
サービス全体の状況。
Bot のオンライン状況、参加サーバー数・メンバー数、接続中の VC 数、メンテナンス状態、未対応の報告数。

```bash
curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/admin/overview" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```
レスポンス例:
```json
{
  "ok": true,
  "bots": [
    {
      "id": "main",
      "name": "VocalX",
      "online": true
    }
  ],
  "server_count": 63,
  "member_count": 7749,
  "live_vc": 2,
  "maintenance": {
    "enabled": false,
    "message": ""
  },
  "open_reports": 0
}
```

### GET /api/v1/admin/sessions  (スコープ: admin)
VocalX が接続している全 VC。
全サーバーの接続中セッションと、VC 内の人数を返します。

```bash
curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/admin/sessions" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```
レスポンス例:
```json
{
  "ok": true,
  "sessions": [
    {
      "guild_id": "111111111111111111",
      "guild_name": "テストサーバー",
      "vc_channel_id": "222222222222222222",
      "vc_channel_name": "雑談",
      "instance_id": "sub",
      "bot_name": "VocalX 2",
      "humans": 3
    }
  ]
}
```

### POST /api/v1/admin/say  (スコープ: admin)
任意のサーバーの VC で読み上げさせる。
VocalX が接続中の VC なら、参加していなくても読み上げさせられます。

パラメータ:
- `guild_id` (body, string, 必須): サーバー ID
- `text` (body, string, 必須): 読み上げる文章 (最大 200 文字)
- `vc_channel_id` (body, string, 任意): VC の ID
- `speaker` (body, string, 任意): 話者
- `speed` (body, number, 任意): 話速

```bash
curl -sS -X POST "https://vocalx.nexxnet.org/api/v1/admin/say" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"guild_id": "111111111111111111", "text": "メンテナンスのお知らせです"}'
```
レスポンス例:
```json
{
  "ok": true,
  "message": "読み上げました"
}
```

### POST /api/v1/admin/leave  (スコープ: admin)
VocalX を VC から退出させる。
指定サーバーで接続中の VocalX を退出させます。

パラメータ:
- `guild_id` (body, string, 必須): サーバー ID
- `vc_channel_id` (body, string, 任意): 対象の VC (省略時は接続中の VC)

```bash
curl -sS -X POST "https://vocalx.nexxnet.org/api/v1/admin/leave" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"guild_id": "111111111111111111"}'
```
レスポンス例:
```json
{
  "ok": true,
  "message": "退出しました"
}
```

### GET /api/v1/admin/maintenance  (スコープ: admin)
メンテナンスモードの状態。

```bash
curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/admin/maintenance" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```
レスポンス例:
```json
{
  "ok": true,
  "enabled": false,
  "message": "ただいまメンテナンス中です。",
  "updated_at": ""
}
```

### PUT /api/v1/admin/maintenance  (スコープ: admin)
メンテナンスモードを切り替える。
有効にすると、管理者以外の Web 画面は止まります (ステータスページは見られます)。

パラメータ:
- `enabled` (body, boolean, 必須): 有効にするか
- `message` (body, string, 任意): 表示するメッセージ (最大 500 文字)

```bash
curl -sS -X PUT "https://vocalx.nexxnet.org/api/v1/admin/maintenance" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "message": "ただいま調整中です。"}'
```
レスポンス例:
```json
{
  "ok": true,
  "enabled": true
}
```

### GET /api/v1/admin/global-dict  (スコープ: admin)
GLOBAL 辞書の一覧。
全サーバー共通の読み替え辞書です。サーバーごとの辞書が優先されます。

```bash
curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/admin/global-dict" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```
レスポンス例:
```json
{
  "ok": true,
  "count": 1,
  "entries": [
    {
      "word": "うぱ様",
      "reading": "うぱさま"
    }
  ]
}
```

### POST /api/v1/admin/global-dict  (スコープ: admin)
GLOBAL 辞書に追加・更新する。
同じ単語があれば読みを更新します。

パラメータ:
- `word` (body, string, 必須): 単語 (最大 100 文字)
- `reading` (body, string, 必須): 読み (最大 200 文字)

```bash
curl -sS -X POST "https://vocalx.nexxnet.org/api/v1/admin/global-dict" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"word": "うぱ様", "reading": "うぱさま"}'
```
レスポンス例:
```json
{
  "ok": true,
  "created": true
}
```

### DELETE /api/v1/admin/global-dict  (スコープ: admin)
GLOBAL 辞書から削除する。

パラメータ:
- `word` (body|query, string, 必須): 削除する単語

```bash
curl -sS -X DELETE "https://vocalx.nexxnet.org/api/v1/admin/global-dict" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"word": "うぱ様"}'
```
レスポンス例:
```json
{
  "ok": true,
  "removed": true
}
```

### GET /api/v1/admin/guilds/{guild_id}/settings  (スコープ: admin)
サーバー設定の取得。
絵文字の読み上げ方 (generic=「絵文字」と読む / name=名前で読む / skip=読まない) など。

パラメータ:
- `guild_id` (path, string, 必須): サーバー ID

```bash
curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/admin/guilds/ID/settings" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```
レスポンス例:
```json
{
  "ok": true,
  "guild_id": "111111111111111111",
  "guild_name": "テストサーバー",
  "emoji_read_mode": "generic"
}
```

### PATCH /api/v1/admin/guilds/{guild_id}/settings  (スコープ: admin)
サーバー設定の変更。
指定した項目だけ変更します。

パラメータ:
- `guild_id` (path, string, 必須): サーバー ID
- `emoji_read_mode` (body, string, 任意): generic / name / skip

```bash
curl -sS -X PATCH "https://vocalx.nexxnet.org/api/v1/admin/guilds/ID/settings" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"emoji_read_mode": "skip"}'
```
レスポンス例:
```json
{
  "ok": true,
  "changed": [
    "emoji_read_mode"
  ]
}
```

### GET /api/v1/admin/reports  (スコープ: admin)
利用者からの報告 (読み方の問題・提案) の一覧。
`/report` で届いた報告です。新しい順に最大 100 件。

パラメータ:
- `status` (query, string, 任意): open / done / rejected (省略時は全件)
- `category` (query, string, 任意): reading / feature / improve / other

```bash
curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/admin/reports" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```
レスポンス例:
```json
{
  "ok": true,
  "count": 1,
  "reports": [
    {
      "id": "b19f794f6a32",
      "created_at": 1790000000.0,
      "category": "reading",
      "status": "open",
      "user_name": "someone",
      "guild_name": "テストサーバー",
      "word": "次参加OK?",
      "reading": "つぎさんかOK?",
      "detail": "じさんかになる",
      "admin_note": ""
    }
  ]
}
```

### POST /api/v1/admin/reports/{report_id}  (スコープ: admin)
報告の状態を更新する。
対応済み・却下にして、管理メモを残せます。

パラメータ:
- `report_id` (path, string, 必須): 報告 ID
- `status` (body, string, 必須): open / done / rejected
- `note` (body, string, 任意): 管理メモ (最大 400 文字)

```bash
curl -sS -X POST "https://vocalx.nexxnet.org/api/v1/admin/reports/ID" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"status": "done", "note": "読み補正を追加しました"}'
```
レスポンス例:
```json
{
  "ok": true
}
```

## エラーコード
- `unauthorized` (HTTP 401): APIキーが無い / 無効
- `forbidden_scope` (HTTP 403): このキーにはこの API を使う権限 (スコープ) が無い
- `bad_request` (HTTP 400): パラメータが不正
- `not_in_vc` (HTTP 409): キーの持ち主が、VocalX の接続中の VC に参加していない
- `ambiguous_vc` (HTTP 409): 参加中の VC が複数ある (guild_id か vc_channel_id で指定する)
- `not_found` (HTTP 404): 対象が見つからない
- `rate_limited` (HTTP 429): リクエストが多すぎる (Retry-After 秒後に再試行)
- `bot_timeout` (HTTP 504): Bot からの応答が時間内に無かった
- `bot_rejected` (HTTP 422): Bot が実行を断った (理由は error に入る)

## 注意
- 読み上げはレート制限あり (既定: 1 キーあたり 1 分 20 回)。429 のときは `Retry-After` 秒待つ。
- 読み上げる文章は最大 200 文字。長い文章は分けて送る。
- APIキーは秘密情報。公開リポジトリ・チャット・ログに貼らない。
- 音声そのものが欲しい場合は音声合成 API (`POST /tts-gw/v1/tts`, 従量課金) を使う。
