API

VocalX API ドキュメント

APIキーだけで、自分が参加している VC で VocalX に読み上げさせる・情報を取得する・設定を変更する、ができます。

AI エージェントに渡す

ChatGPT・Claude などの AI や自動化ツールにこの API を使わせたいときは、下のボタンで説明文をコピーして貼り付けるだけです。 API の使い方・エラー対処まで 1 つにまとまっています。

agent.md (Markdown) OpenAPI (JSON)

コピーされる説明文に APIキーは含まれません (<YOUR_API_KEY> の部分は自分で置き換えてください)。 キーは秘密情報なので、公開の場所には貼らないでください。

はじめかた

  1. アカウント設定 の「API キー」で、「VocalX の操作 API」にチェックを入れてキーを発行します (キーは一度しか表示されません)。
  2. VocalX が参加している VC に入ります。
  3. 下のコマンドを実行すると、その VC で読み上げが始まります。
curl -sS -X POST "https://vocalx.nexxnet.org/api/v1/bot/say" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "こんにちは、テストです"}'
認証Authorization: Bearer <キー> (または X-API-Key)
制限読み上げは 1 分 20 回まで / 1 回 200 文字まで
料金操作 API は無料。音声データの生成 (/tts-gw/v1/tts) は従量課金
音声データを生成する TTS Gateway は /tts-gw/ に移動しました (/tts-gw/v1/tts など)。/api/v1/tts などの旧パスと、旧い画面のURLも引き続き使えます。 TTS Gateway を開く

キーの権限 (スコープ)

  • tts 音声合成 API。すべてのキーが持つ (従来どおり)。
  • bot 操作 API。自分が参加中の VC で読み上げさせる / 状況の取得 / 自分の読み上げ設定の変更。APIキー発行時に「VocalX の操作 API」を選ぶ。無料。
  • admin 管理 API。サービス管理者のキーだけが持てる。bot 権限を含み、管理操作もできる。

操作 API bot

GET /api/v1/bot/me bot

キーの持ち主と権限を確認する

接続テストにも使えます。このキーに付いているスコープ、管理者かどうか、現在のプランを返します。

curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/bot/me" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx"
レスポンス例
{
  "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 にも居ない」ことを表します。情報は十数秒おきに更新されます。

curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/bot/session" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx"
レスポンス例
{
  "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 には送れません。

名前場所型必須説明
textbodystring 必須 読み上げる文章 (最大 200 文字。プランの上限でさらに短くなることがある)
guild_idbodystring 任意 サーバー ID。参加中の VC が複数あるときに指定
vc_channel_idbodystring 任意 VC の ID。参加中の VC が複数あるときに指定
speakerbodystring 任意 話者 ID または名前 (省略時は自分の設定 → サーバーの設定の順)
speedbodynumber 任意 話速 (プランの範囲に自動で調整される)
curl -sS -X POST "https://vocalx.nexxnet.org/api/v1/bot/say" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "こんにちは、テストです", "speed": 1.0}'
レスポンス例
{
  "ok": true,
  "message": "読み上げました",
  "guild_id": "111111111111111111",
  "vc_channel_id": "222222222222222222",
  "instance_id": "sub"
}
GET /api/v1/bot/settings bot

自分の読み上げ設定を取得する

Web の「読み上げ設定」と同じ内容です。`speaker` が null なら「サーバーの設定に従う」です。

curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/bot/settings" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx"
レスポンス例
{
  "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 で拒否されます。

名前場所型必須説明
speakerbodystring|null 任意 話者 ID または名前
speedbodynumber|null 任意 話速
callnamebodystring|null 任意 呼び名 (最大 20 文字)
curl -sS -X PATCH "https://vocalx.nexxnet.org/api/v1/bot/settings" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"speaker": "ずんだもん", "speed": 1.0}'
レスポンス例
{
  "ok": true,
  "changed": [
    "speaker",
    "speed"
  ]
}

管理 API admin

サービス管理者のキー (admin スコープ) だけが使えます。

GET /api/v1/admin/overview admin

サービス全体の状況

Bot のオンライン状況、参加サーバー数・メンバー数、接続中の VC 数、メンテナンス状態、未対応の報告数。

curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/admin/overview" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx"
レスポンス例
{
  "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 内の人数を返します。

curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/admin/sessions" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx"
レスポンス例
{
  "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_idbodystring 必須 サーバー ID
textbodystring 必須 読み上げる文章 (最大 200 文字)
vc_channel_idbodystring 任意 VC の ID
speakerbodystring 任意 話者
speedbodynumber 任意 話速
curl -sS -X POST "https://vocalx.nexxnet.org/api/v1/admin/say" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"guild_id": "111111111111111111", "text": "メンテナンスのお知らせです"}'
レスポンス例
{
  "ok": true,
  "message": "読み上げました"
}
POST /api/v1/admin/leave admin

VocalX を VC から退出させる

指定サーバーで接続中の VocalX を退出させます。

名前場所型必須説明
guild_idbodystring 必須 サーバー ID
vc_channel_idbodystring 任意 対象の VC (省略時は接続中の VC)
curl -sS -X POST "https://vocalx.nexxnet.org/api/v1/admin/leave" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"guild_id": "111111111111111111"}'
レスポンス例
{
  "ok": true,
  "message": "退出しました"
}
GET /api/v1/admin/maintenance admin

メンテナンスモードの状態

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

メンテナンスモードを切り替える

有効にすると、管理者以外の Web 画面は止まります (ステータスページは見られます)。

名前場所型必須説明
enabledbodyboolean 必須 有効にするか
messagebodystring 任意 表示するメッセージ (最大 500 文字)
curl -sS -X PUT "https://vocalx.nexxnet.org/api/v1/admin/maintenance" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "message": "ただいま調整中です。"}'
レスポンス例
{
  "ok": true,
  "enabled": true
}
GET /api/v1/admin/global-dict admin

GLOBAL 辞書の一覧

全サーバー共通の読み替え辞書です。サーバーごとの辞書が優先されます。

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

GLOBAL 辞書に追加・更新する

同じ単語があれば読みを更新します。

名前場所型必須説明
wordbodystring 必須 単語 (最大 100 文字)
readingbodystring 必須 読み (最大 200 文字)
curl -sS -X POST "https://vocalx.nexxnet.org/api/v1/admin/global-dict" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"word": "うぱ様", "reading": "うぱさま"}'
レスポンス例
{
  "ok": true,
  "created": true
}
DELETE /api/v1/admin/global-dict admin

GLOBAL 辞書から削除する

名前場所型必須説明
wordbody|querystring 必須 削除する単語
curl -sS -X DELETE "https://vocalx.nexxnet.org/api/v1/admin/global-dict" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"word": "うぱ様"}'
レスポンス例
{
  "ok": true,
  "removed": true
}
GET /api/v1/admin/guilds/{guild_id}/settings admin

サーバー設定の取得

絵文字の読み上げ方 (generic=「絵文字」と読む / name=名前で読む / skip=読まない) など。

名前場所型必須説明
guild_idpathstring 必須 サーバー ID
curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/admin/guilds/ID/settings" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx"
レスポンス例
{
  "ok": true,
  "guild_id": "111111111111111111",
  "guild_name": "テストサーバー",
  "emoji_read_mode": "generic"
}
PATCH /api/v1/admin/guilds/{guild_id}/settings admin

サーバー設定の変更

指定した項目だけ変更します。

名前場所型必須説明
guild_idpathstring 必須 サーバー ID
emoji_read_modebodystring 任意 generic / name / skip
curl -sS -X PATCH "https://vocalx.nexxnet.org/api/v1/admin/guilds/ID/settings" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"emoji_read_mode": "skip"}'
レスポンス例
{
  "ok": true,
  "changed": [
    "emoji_read_mode"
  ]
}
GET /api/v1/admin/reports admin

利用者からの報告 (読み方の問題・提案) の一覧

`/report` で届いた報告です。新しい順に最大 100 件。

名前場所型必須説明
statusquerystring 任意 open / done / rejected (省略時は全件)
categoryquerystring 任意 reading / feature / improve / other
curl -sS -X GET "https://vocalx.nexxnet.org/api/v1/admin/reports" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx"
レスポンス例
{
  "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_idpathstring 必須 報告 ID
statusbodystring 必須 open / done / rejected
notebodystring 任意 管理メモ (最大 400 文字)
curl -sS -X POST "https://vocalx.nexxnet.org/api/v1/admin/reports/ID" \
  -H "Authorization: Bearer vxak_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "done", "note": "読み補正を追加しました"}'
レスポンス例
{
  "ok": true
}

エラー

失敗したときは {"ok": false, "error": "メッセージ", "code": "コード"} を返します。code で処理を分けてください。

codeHTTP意味
unauthorized401APIキーが無い / 無効
forbidden_scope403このキーにはこの API を使う権限 (スコープ) が無い
bad_request400パラメータが不正
not_in_vc409キーの持ち主が、VocalX の接続中の VC に参加していない
ambiguous_vc409参加中の VC が複数ある (guild_id か vc_channel_id で指定する)
not_found404対象が見つからない
rate_limited429リクエストが多すぎる (Retry-After 秒後に再試行)
bot_timeout504Bot からの応答が時間内に無かった
bot_rejected422Bot が実行を断った (理由は error に入る)