VocalX API ドキュメント
APIキーだけで、自分が参加している VC で VocalX に読み上げさせる・情報を取得する・設定を変更する、ができます。
AI エージェントに渡す
ChatGPT・Claude などの AI や自動化ツールにこの API を使わせたいときは、下のボタンで説明文をコピーして貼り付けるだけです。 API の使い方・エラー対処まで 1 つにまとまっています。
コピーされる説明文に APIキーは含まれません (<YOUR_API_KEY> の部分は自分で置き換えてください)。
キーは秘密情報なので、公開の場所には貼らないでください。
はじめかた
- アカウント設定 の「API キー」で、「VocalX の操作 API」にチェックを入れてキーを発行します (キーは一度しか表示されません)。
- VocalX が参加している VC に入ります。
- 下のコマンドを実行すると、その 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)/tts-gw/v1/tts) は従量課金/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
/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
}
}
/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
}
]
}
/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 | 任意 | 話速 (プランの範囲に自動で調整される) |
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"
}
/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
]
}
/api/v1/bot/settings
bot
自分の読み上げ設定を変更する
指定した項目だけ変更します。null を渡すとその項目を初期化します (サーバーの設定に従う)。プランで許されない話者・話速は 400 で拒否されます。
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
speaker | body | string|null | 任意 | 話者 ID または名前 |
speed | body | number|null | 任意 | 話速 |
callname | body | string|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 スコープ) だけが使えます。
/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
}
/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
}
]
}
/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 | 任意 | 話速 |
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": "読み上げました"
}
/api/v1/admin/leave
admin
VocalX を VC から退出させる
指定サーバーで接続中の VocalX を退出させます。
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
guild_id | body | string | 必須 | サーバー ID |
vc_channel_id | body | string | 任意 | 対象の 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": "退出しました"
}
/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": ""
}
/api/v1/admin/maintenance
admin
メンテナンスモードを切り替える
有効にすると、管理者以外の Web 画面は止まります (ステータスページは見られます)。
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
enabled | body | boolean | 必須 | 有効にするか |
message | body | string | 任意 | 表示するメッセージ (最大 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
}
/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": "うぱさま"
}
]
}
/api/v1/admin/global-dict
admin
GLOBAL 辞書に追加・更新する
同じ単語があれば読みを更新します。
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
word | body | string | 必須 | 単語 (最大 100 文字) |
reading | body | string | 必須 | 読み (最大 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
}
/api/v1/admin/global-dict
admin
GLOBAL 辞書から削除する
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
word | body|query | string | 必須 | 削除する単語 |
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
}
/api/v1/admin/guilds/{guild_id}/settings
admin
サーバー設定の取得
絵文字の読み上げ方 (generic=「絵文字」と読む / name=名前で読む / skip=読まない) など。
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
guild_id | path | string | 必須 | サーバー 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"
}
/api/v1/admin/guilds/{guild_id}/settings
admin
サーバー設定の変更
指定した項目だけ変更します。
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
guild_id | path | string | 必須 | サーバー ID |
emoji_read_mode | body | string | 任意 | 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"
]
}
/api/v1/admin/reports
admin
利用者からの報告 (読み方の問題・提案) の一覧
`/report` で届いた報告です。新しい順に最大 100 件。
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
status | query | string | 任意 | open / done / rejected (省略時は全件) |
category | query | string | 任意 | 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": ""
}
]
}
/api/v1/admin/reports/{report_id}
admin
報告の状態を更新する
対応済み・却下にして、管理メモを残せます。
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
report_id | path | string | 必須 | 報告 ID |
status | body | string | 必須 | open / done / rejected |
note | body | string | 任意 | 管理メモ (最大 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 で処理を分けてください。
| code | HTTP | 意味 |
|---|---|---|
unauthorized | 401 | APIキーが無い / 無効 |
forbidden_scope | 403 | このキーにはこの API を使う権限 (スコープ) が無い |
bad_request | 400 | パラメータが不正 |
not_in_vc | 409 | キーの持ち主が、VocalX の接続中の VC に参加していない |
ambiguous_vc | 409 | 参加中の VC が複数ある (guild_id か vc_channel_id で指定する) |
not_found | 404 | 対象が見つからない |
rate_limited | 429 | リクエストが多すぎる (Retry-After 秒後に再試行) |
bot_timeout | 504 | Bot からの応答が時間内に無かった |
bot_rejected | 422 | Bot が実行を断った (理由は error に入る) |