NEO実装APIについて

ゆかコネNEO v3.0 のドキュメントです。v2.3 をお使いの方は v2.3 版のこのページ を、違いを知りたい方は v2.3 から v3.0 への移行 をご覧ください。

内容について

この内容はサービス改良の中で予告なく改定されることがあります

ゆかコネNEOは、本体の中にWebサーバとWebSocketサーバを持っています。外部のツールから、字幕の受信や設定変更ができます。

通信ポートについて

ポート番号は固定ではありません

ゆかコネNEOは、起動時に使えるポートを自動的に探します。ほかのソフトがポートを使っていた場合は、別のポートに変わります。 実際に使われているポート番号は、必ずレジストリから取得してください。

• レジストリ位置：HKCU\Software\YukarinetteConnectorNeo\

名前	型	意味
HTTP	DWord32	HTTPポート番号
WebSocket	DWord32	WebSocketポート番号
LayoutDir	String	字幕テンプレートが置かれているフォルダ

• ポートを開放したときに更新されます。

項目	既定のポート番号
HTTP	11900
WebSocket	11901

• 「ネットワークの設定」画面の「使える通信ポートを自動で選びます」をOFFにすると、11900 / 11901 に固定されます。

このページの例について

このページのURLの例では 11900 / 11901 を使っていますが、あくまで例です。お使いの環境では別の番号になっていることがあります。

以前から使っている環境について

• ポート番号はレジストリに記録され、次の起動でも引き継がれます。そのため、以前から使っている環境では 15520 などの別の番号になっていることがあります。
• それは正常です。番号を 11900 に直す必要はありません。レジストリから読んだ値をそのまま使ってください。

プラグインのポートについて

「翻訳・発話連携」プラグインは、本体とは別のポートを持っています。そちらはサブキー HKCU\Software\YukarinetteConnectorNeo\TransServer\ の HTTP / WebSocket を参照してください。詳しくは プラグイン系API をご覧ください。

アクセス制御について

v3.0.8 から、守りが強くなりました

悪意のある Web ページが、裏でこの PC の http://localhost:… を叩いて字幕を差し込んだり設定を書き換えたりできないよう、 「誰からの要求か」を見て断るようになりました。自作ツールが急に動かなくなったときは、この節と「ネットワークの設定」画面の アクセス状況 を確認してください。

待ち受ける範囲

• 既定では、同じパソコンの中からしか接続できません（127.0.0.1 のみで待ち受けます）。
• 「ネットワークの設定」画面の「すべてのIPアドレスを有効にする」をONにし、かつ管理者としてゆかコネNEOを起動した場合のみ、ほかの端末から接続できるようになります。
• ほかの端末から接続できる状態のとき、受け付けられるのは次のものだけです。
  • 同じパソコン（ループバック）
  • プライベートIPアドレス（10.／192.168.／172.16～172.31 で始まるもの）
  • 「ネットワークの設定」画面のWeb許可ホストに書いたアドレス（改行区切り。前方一致）
• 上記以外からのアクセスは、HTTPなら 403 - Forbidden、WebSocketなら接続が切られます。

名前（Host）の確認

• localhost・IP アドレス・この PC のコンピューター名（名前.local を含む）・Web許可ホストに書いた名前以外で来た要求は、どの口でも断ります（DNS リバインディング対策）。
• Tailscale や hosts の別名など、独自の名前でこの PC を開く場合は、その名前を Web許可ホストに書いてください。

書き込み（字幕の送信・設定の変更・操作）

/api/ の下は、/api/getlayoutdata /api/mute-status /api/ruby-status の読むだけのものを除いて書き込みとして扱います。字幕テンプレートや画像などのファイルの読み込みは、上の「待ち受ける範囲」と「名前の確認」だけで判断します。

呼び出し元	書き込み
この PC のブラウザ以外の道具（Stream Deck・自作スクリプト・Node.js アプリなど）	そのまま受け付けます
この PC のブラウザで開いた、信頼できるページ（下記）	受け付けます
この PC のブラウザで開いた、知らないページ	403 で断ります
ほかの端末（LAN）	トークンが必要です。無い・違うときは 403 - Forbidden (token required)

• 信頼できるページとは、ゆかコネNEO が配るページ（localhost・127.0.0.1・[::1] のどのポートでも）、ブラウザ音声認識のページ（https://yukari-connect.app）、ブラウザの拡張機能、Web許可ホストに書いたページ（https://～ のように書くとスキームとホストを比べ、ポートを書いたときはポートも比べます）です。
• Origin が null のページや file:// で開いたページは信頼しません。
• 字幕の中の <img src="/api/…"> のように、画像やスクリプトとして読み込ませた要求は、書き込みとしては受け付けません。

LAN からの操作に使うトークン

• ほかの端末から書き込むときは、ヘッダー X-YNC-Token か、URL のクエリ ?token=… でトークンを付けます。
• トークンは「ネットワークの設定」画面の 「LAN からの操作に使うトークン」 の 「コピー」 で写せます（画面には表示されません）。「作り直す」 で新しくすると、前のトークンは使えなくなります。
• トークンは設定フォルダの local-api-token に置かれ、設定の書き出しには含まれません。

Query（LAN から）

    http://192.168.0.10:11900/api/input?text=あいうえお&token=（コピーしたトークン）

WebSocket の扱い

呼び出し元	扱い
この PC の道具・信頼できるページ	送受信できます
配信ソフト（OBS・Streamlabs・XSplit・vMix）でローカルファイルとして開いたテンプレート	字幕を受け取るだけ（送ったものは使いません）
知らないページ	つなぎません
ほかの端末（LAN）	トークン（?token=）が無ければ受け取るだけ。トークンを付ければ送信もできます

ブラウザから呼び出す場合（CORS）

• 信頼できるページから呼び出したときは、そのオリジンを Access-Control-Allow-Origin に返します。Origin の付いていない要求には * を返します。知らないページには返しません。
• Access-Control-Allow-Methods: GET, POST, OPTIONS ／ Access-Control-Allow-Headers: Content-Type, X-YNC-Token が付きます。

断られた理由を確かめる

「ネットワークの設定」画面の アクセス状況 に、直近 20 件の許可・拒否と理由（許可していない IP／許可していないホスト名／知らない Web ページから／トークンなし／トークン違い など）が出ます。 詳しくは オプション設定項目 をご覧ください。

共有ネットワークでの利用について

「すべてのIPアドレスを有効にする」をONにすると、同じネットワークにいる人がテンプレートを開いたり、字幕を受け取ったりできるようになります。ネットカフェや共有Wi-Fiなど、信頼できないネットワークではONにしないでください。 トークンを知られたときは、すぐに「作り直す」を押してください。

入力の受付

• 外部ツールから指定された文字を文字入力として受け付けます。

使用条件

• 特になし

• 送付方式：GET
• 送付先 : /api/input

クエリ	意味	例
text	文章	あいうえお
fixedText	確定したか（省略時は true）	true / false
textID	テキスト固有ID（省略時は自動生成）	4C6E8172-2048-4995-BF36-3893EF31FA67
name	ユーザ名を使うためのスイッチ	（後述）
UserID	ユーザID	0001-002-0003-00005
TalkerName	ユーザ名	さいとう
owner	発話の由来名（省略時は API）	MyTool
forceInput	ミュート中でも入力する（省略時は false）	true / 1

QueryQuery（名前つき）

{
    http://localhost:11900/api/input?text=あいうえお
}

{
    http://localhost:11900/api/input?text=あいうえお&name=&UserID=0001-002&TalkerName=さいとう
}

• 成功すると ok が返ってきます。

ミュート中は入力されません

• /api/input はミュートに従います。ミュート中は表示も読み上げもされず、ok の代わりに mute が返ります（ステータスは 200 のままです）。
• 以前はミュート中でも表示されていました。ミュート中でも出したい場合は forceInput=true を付けてください。
• true のほかに 1 on yes も使えます。

name を付けないと名前が反映されません

• UserID と TalkerName は、クエリに name というキーが含まれているときだけ読み取られます。
• name の値は使われません。name= のように空でもかまいません。「名前を使う」というスイッチとして働きます。
• name を書き忘れると、UserID と TalkerName は無視されて名前が付きません。

入力の受付(拡張)

• 外部ツールから指定された文字を文字入力として受け付けます。

使用条件

• ゆかコネNEO v2.0.104～

• 送付方式：POST
• 送付先 : /api/input

パラメータ	値	例
ignorePlugin	実行しないプラグインID（JSON配列で指定）	["Plugin_GPT3"]
Text	文章	おはよう!天気がいいね
UserID	ユーザID	0001-002-0003-00005
TalkerName	ユーザ名	さいとう
ServiceName	発話の由来名（省略時は API）	MyTool
fixedText	確定したか (v2.3.104～)	true
textID	テキスト固有ID (v2.3.104～)	4C6E8172-2048-4995-BF36-3893EF31FA67
forceInput	ミュート中でも入力する（省略時は false）	true
Morph	ルビ（読み）の指定 (v3.0.0 beta 22～)（JSON配列で指定）	[{"writtenForm":"形態素","spokenForm":"けいたいそ"}]

QueryBody

{
    http://localhost:11900/api/input
}

{
    "ignorePlugin":
    [
        "Plugin_GPT3"
    ],
    "Text":"おはよう!天気がいいね",
    "fixedText": true,
    "textID": "4C6E8172-2048-4995-BF36-3893EF31FA67",
    "UserID": "0001-002-0003-00005",
    "TalkerName": "さいとう",
    "ServiceName": "MyTool",
    "Morph":
    [
        { "writtenForm": "今日", "spokenForm": "きょう" },
        { "writtenForm": "天気", "spokenForm": "てんき" }
    ]
}

• 成功すると ok が返ってきます。
• ユーザ名を設定するときには UserIDも指定してください。UserIDが無い場合、TalkerNameは無視されます。
• UserIDは、ユーザを識別するものなので、ユーザに対して一意となるものにしてください。(一般的には配信サイトから提供されるユニークなユーザIDなどを使います)
• ingorePlugin は、実行しないプラグインを指定できます。（なお、 プラグイン名は大文字・小文字を区別する点に注意してください)
• 途中経過を送る場合には、fixedTextを使います。最初はfalse で経過を送り、最後に確定として True を送ります。IDごとに、かならず 最後にtrueが送られるようにしましょう。
• ミュート中は送らずに mute が返ります。ミュート中でも入力したい場合は forceInput を true にします。ボディでの指定が優先され、無ければ URL のクエリを見ます。
• 確定（fixedText が true）で textID が空のときは、本体が ID を振って受け付けます。途中経過（false）で textID が空のときは捨てられます。

ignorePlugin は配列で指定してください

"ignorePlugin": "Plugin_GPT3" のように文字列を直接書くとエラーになります。1つだけ指定する場合も ["Plugin_GPT3"] と書いてください。

Morph でルビ（読み）を指定できます

• POST のときだけ受け取ります。GET のクエリにはありません。
• writtenForm（文字）と spokenForm（読み）の組を、文中に現れる順で並べた配列です。
• ルビを字幕に描くのは本体です (v3.0.0 beta 23～)。「字幕デザイン」→「デザイン」→ 分類のタブ「表示」の 「ルビの表示（対応している場合）」 が ON のときだけ表示されます（/api/ruby-on でも切り替えられます）。ルビに対応していないテンプレートでは表示されません。
• 指定した組は、その文の形態素解析（MeCab）の代わりに使われます。渡した組だけがルビになり、残りの文字にはルビが付きません。ルビ付与プラグインが無効でも、指定した読みでルビが付きます。
• 当たるのは入力した文が表示される段だけです。翻訳後の段（日本語・中国語）には、ルビ付与プラグインが有効ならそのプラグインが作ったルビが付きます。
• 指定した組はプラグインには渡りません（語と読みの組を本体の外へ出さないためです）。プラグインへ渡るのは、組から作った読み上げ用のかな（ReadingPhrase）だけで、読み上げの読みにも使われます。
• 文中に見つからない writtenForm は読み飛ばされます（エラーにはなりません）。
• spokenForm を空にすると、その文字はルビ無しで表示されます。読み上げでは、その文字がそのまま読まれます。

認識のミュート

• 入力をシャットアウトします

API からの入力もミュートに従います

• UDトーク・IPtalk・ブラウザ音声認識からの入力に加えて、/api/input から入れた文字も捨てられます。
• ミュート中でも /api/input から出したい場合は forceInput=true を付けてください。

使用条件

• 特になし

• 送付方式：GET
• 送付先 : /api/mute-**

Mute OnMute offMute toggle

    http://localhost:11900/api/mute-on

    http://localhost:11900/api/mute-off

    http://localhost:11900/api/mute-toggle

• 状態が変わったときは ok が返ってきます。
• すでにその状態だった場合は stay が返ってきます。（エラーではありません）
• mute-toggle は、呼ぶたびにミュートの ON / OFF を入れ替えます。切り替えたあとの状態が返ってきます（ミュートになったら mute-on、解除されたら mute-off）。
  • StreamDeck などで、1 つのボタンでミュートを切り替えたいときに使います。

ミュート状態の取得

• いまミュート中かどうかを確認します。

使用条件

• 特になし

• 送付方式：GET
• 送付先 : /api/mute-status

Query

    http://localhost:11900/api/mute-status

• ミュート中なら true、そうでなければ false が返ってきます。
• StreamDeckなどで、ボタンの点灯状態をゆかコネNEOに合わせたいときに使います。

ルビの表示の切替

• 「字幕デザイン」→「デザイン」→ 分類のタブ「表示」の 「ルビの表示（対応している場合）」 を切り替えます。

使用条件

• ゆかコネNEO v3.0.0 beta 23～

• 送付方式：GET
• 送付先 : /api/ruby-**

Ruby OnRuby off

    http://localhost:11900/api/ruby-on

    http://localhost:11900/api/ruby-off

• 状態が変わったときは ok が返ってきます。
• すでにその状態だった場合は stay が返ってきます。（エラーではありません）
• 画面のチェックを切り替えたのと同じ扱いです。設定の保存や、表示中の字幕の描き直しも画面から切り替えたときと同じように行われます。

ルビの表示状態の取得

• いま「ルビの表示（対応している場合）」が ON かどうかを確認します。

使用条件

• ゆかコネNEO v3.0.0 beta 23～

• 送付方式：GET
• 送付先 : /api/ruby-status

Query

    http://localhost:11900/api/ruby-status

• ON なら true、OFF なら false が返ってきます。

母国語設定の変更

• 指定した言語に母国語設定を変更します

使用条件

• ゆかコネNEO v2.0以上

• 送付方式：GET
• 送付先 : /api/setRecognitionParam

クエリ	意味	例
language	言語名（ISO表記)	ja

Query

    http://localhost:11900/api/setRecognitionParam?language=ja

• 選択・認知可能な言語であれば変更を反映します
• language は必須です。 省略した場合や、知らない言語名を指定した場合は、何も起きません（設定は変わりません）。
• 言語名は ja のようなISO表記のほか、JA のような大文字の短縮形も受け付けます。

認識言語スロットの切替

• ブラウザ音声認識の画面で選べる「認識する言語」を、1～3番目のどれにするか切り替えます。

使用条件

• ブラウザ音声認識（Chrome / Edge）を使用中であること
• 音声認識ウィンドウが開いていること

• 送付方式：GET
• 送付先 : /api/setRecognitionMode

クエリ	意味	例
number	認識言語の番号（1～3）	2

Query

    http://localhost:11900/api/setRecognitionMode?number=2

母国語の変更とは別物です

• こちらは音声認識ウィンドウの言語プルダウンを切り替える機能です。
• 母国語そのものを変えたい場合は /api/setRecognitionParam を使ってください。
• ブラウザ音声認識以外（オフライン認識・UDトークなど）を使っているときは効きません。

翻訳表示設定の変更

• 翻訳字幕表示設定を変更します

使用条件

• ゆかコネNEO v2.0以上

• 送付方式：GET
• 送付先 : /api/setTranslationParam

クエリ	意味	例
slot	翻訳ナンバー	1~4
language	言語名（ISO表記）	下表を参照
engine	翻訳エンジン設定	下表を参照

Query

    http://localhost:11900/api/setTranslationParam?slot=1&language=en&engine=deeplpro

• 選択・認知可能な言語であれば変更を反映します

利用条件の同意が要るエンジン（v3.0.1～）

• plamo mirai textra offline は、先にゆかコネNEO の画面で利用条件に同意しておく必要があります（翻訳エンジンの一覧からそのエンジンを一度選ぶと、同意を聞かれます）。
• 同意していないときは切り替えず、状態コード 403 と次の JSON を返します。/api/setconfig で同じエンジンを指定したときも同じです（ほかの設定は反映され、そのエンジンの欄だけ元のままになります）。

{"result":"error","reason":"terms_not_accepted","engines":["textra"],"message":"..."}

language に指定できる特別な値

language	意味
ja en zh-TW …	その言語に翻訳します（ISO表記）
off	この枠を使わない（翻訳しない）
none	off と同じです
native	翻訳せず、母国語をそのまま表示します

engine に指定できる値

engine	ID	翻訳エンジン	状態	備考
google	0	Google 翻訳v2(支援①～)	利用可
microsoft	1	Microsoft翻訳システム(支援①～)	利用可
deeplpro	2	DeepL API Pro翻訳エンジン(支援③～)	利用可
deeplfree	3	DeepL API Free翻訳エンジン(個人でKey取得)	利用可
amazon	4	Amazon 翻訳システム(Asia向け/支援③～)	利用可
amazon-eu	5	Amazon 翻訳システム(EU圏向け/支援③～)	利用可
googletrans	6	—	廃止	v2.3.128でエンジン一覧から削除しました。指定しても選択は変わりません
watson	7	—	廃止	v2.3.128でエンジン一覧から削除しました。指定しても選択は変わりません
papago	8	NAVER Papago 翻訳システム(支援③～)	利用可
papago-app	9	NAVER Papago 翻訳システム(個人キー)	利用可
share	10	共用翻訳(m2m100/無料)	利用可
gas	11	Google Apps Script 翻訳（個人で用意）	利用可
googlev3	12	Google 翻訳V3 (支援③～)	利用可
gpt4.1	13	OpenAI GPT4.1 API翻訳(支援③～/β)	利用可
tencent	14	Tencent Cloud Translator(個人キー)	利用可
baidu	15	Baidu(百度)Translator (個人キー)	利用可
roman	16	Microsoftローマ字変換（支援①～)	利用可
alibaba	17	Alibaba クラウド翻訳(個人キー)	利用可
—	18	共用翻訳(Algos/より良い翻訳/支援①～)	APIからは指定できません	アプリの一覧には表示されます
gpt4.1mini	19	OpenAI GPT-4.1-mini(支援③～/β)	利用可
gpt4.1nano	20	OpenAI GPT-4.1-nano(支援③～/β)	利用可
gemini25flash	21	Google Gemini Flash Lite API翻訳(個人キー)	利用可	使うモデルは 3.5 Flash Lite に固定されます（v3.0～。v2.3 では 2.5 Flash Lite でした）。engine 名は改名していません
gemini25pro	22	Google Gemini API翻訳(個人キー)	利用可	使うモデルは「APIキーの設定」画面の MODEL で決まります。値の名前は pro ですが、選んだモデルがそのまま使われます
claude	23	Anthropic Claude （個人キー)	利用可
openrouter	24	OpenRouter API (個人キー)	利用可
grok	25	Grok AI 翻訳(個人キー)	利用可
custom	26	ローカル翻訳（個人API）	利用可
—	27	ブラウザ翻訳（β/Free）	APIからは指定できません	アプリの一覧には表示されます
off	28	OFF（翻訳しない）	利用可
parapper	29	Parapper翻訳	利用可	v2.3.128～
plamo	30	PLaMo 翻訳(個人キー)	利用条件に同意済みのときだけ	v3.0.0 beta 37～
mirai	31	みらい翻訳(個人キー)	利用条件に同意済みのときだけ	v3.0.0 beta 37～
textra	32	みんなの自動翻訳＠TexTra(個人キー)	利用条件に同意済みのときだけ	v3.0.0 beta 37～
offline	33	オフライン翻訳（無料）	ライセンスに同意済みのときだけ	v3.0.0～。PCの中で動く翻訳です

この表の基準

• ゆかコネNEO v2.3.128 時点の一覧です。
• 値は 大文字・小文字を区別します。Papago は無効で、papago が正しい表記です。
• 一覧にない文字列を指定した場合、翻訳エンジンの選択は変更されません。
• ID18 と ID27 は、アプリの一覧には出てきますがAPIから指定する値が用意されていません。この2つに切り替えたい場合は画面から操作してください。

値の変更履歴

• v2.3.128：gemini15flash → gemini25flash、gemini15pro → gemini25pro に改名しました（旧名は使えません）
• v2.3.128：parapper を追加しました
• v2.3.128：googletrans watson を廃止しました
• v3.0：gemini25flash (ID 21) が使うモデルを 2.5 Flash Lite から 3.5 Flash Lite に変更しました（engine 名はそのまま）

設定の変更

• 設定項目を外部から書き換えます。

使用条件

• Parapper_TransPort の対応は ゆかコネNEO v2.3.128～

• 送付方式：POST（Content-Type: application/json）
• 送付先 : /api/setconfig

キー	型	意味
NativeLanguage	int	母国語の選択番号
TranslateLanguage1 ～ TranslateLanguage4	string	翻訳先の言語名
Translator1String ～ Translator5String	string	翻訳エンジンの表示名（画面の一覧と同じ文字）
Translator1 ～ Translator5	int	翻訳エンジンの ID（上の「engine に指定できる値」の ID）。Translator1String などと両方あるときは表示名が優先されます
KeepTime	double	字幕の保持時間（秒）
ScrollTime	double	スクロール速度
Parapper_TransPort	int	Parapper翻訳の接続先ポート（1～65535）
ShowRuby	bool	ルビの表示（対応している場合）の ON／OFF (v3.0.0 beta 23～)

• 利用条件の同意が要るエンジン（PLaMo・みらい翻訳・TexTra・オフライン翻訳）は、同意していなければ切り替わらず 403 を返します（翻訳表示設定の変更 を参照）。

QueryBody

    POST http://localhost:11900/api/setconfig

{
    "YNC-NEO": {
        "Parapper_TransPort": 18081
    }
}

• 受け付けると 200 が返ります。
• OPTIONS は 204 を返します（ブラウザから呼び出すときの事前確認用）。
• POST OPTIONS 以外のメソッド、JSONとして解釈できない本文は 400 を返します。
• 一覧にないキーは無視されます。エラーにはなりません。

200は「反映が終わった」という意味ではありません

• 設定の反映は、受け付けたあとに非同期で行われます。
• /api/setconfig を送った直後に /api/setTranslationParam などを送ると、反映の順序が入れ替わることがあります。続けて送る場合は少し間隔をあけてください。
• 同じことは /api/setRecognitionParam /api/setRecognitionMode /api/setTranslationParam にもあてはまります。

ステータスコードで成否を判断しないでください

• 設定変更系のAPIは、処理が終わる前に応答を返します。そのため、200 が返っても指定した値が反映されていないことがあります（たとえば language だけ有効で engine の指定が無効だった場合など）。
• 反映されたかどうかを確かめたい場合は、/api/getlayoutdata で現在の設定を読み直してください。

扱えるキーについて

• ここに載せているキーだけが動作を保証している範囲です。
• 本文の "YNC-NEO" は省略して {"Parapper_TransPort": 18081} と書くこともできますが、将来の互換性のため付けることを推奨します。

設定一式の取得

• 現在の設定をまとめてJSONで取得します。

使用条件

• 特になし

• 送付方式：GET
• 送付先 : /api/getlayoutdata

Query

    http://localhost:11900/api/getlayoutdata

• 言語・翻訳エンジン・フォント・色・保持時間・レイアウトなど、設定一式がJSONで返ります。
• v3.0.0 beta 23 からは、ルビの表示（対応している場合）の ON／OFF が ShowRuby に入ります。/api/setlayoutdata で送り返すと復元されます。
• 外部ツールで設定のバックアップを取ったり、いまの状態を確認したりするのに使えます。

設定一式の復元

• /api/getlayoutdata で取得したJSONを送り返して、設定を復元します。

使用条件

• 特になし

• 送付方式：POST（Content-Type: application/json）
• 送付先 : /api/setlayoutdata

Query

    POST http://localhost:11900/api/setlayoutdata

• 本文には /api/getlayoutdata で得たJSONをそのまま入れてください。
• /api/setconfig と違い、"YNC-NEO" で囲む必要はありません。
• 外部ツールで「配信用プリセット」「コラボ用プリセット」を切り替えるような使い方ができます。

画面から使う場合

同じことは「設定保存・復元」画面や、起動オプションの /profile= でもできます。詳しくは 設定の保存・復元とプロファイル と 起動オプション をご覧ください。

プラグインコマンド

• プラグイン特有のコマンドを送付します

使用条件

• プラグイン自体が対応していること
• 対象のプラグインが有効になっていること

• 送付方式：GET
• 送付先 : /api/command

クエリ	意味	例
target	送付先プラグイン識別名	Plugin_OBS5
command	命令文字列	scene

• 応答は、プラグインが返した文字列がそのまま返ります。 ok は返りません。
• 返ってきた内容がJSONとして解釈できる場合は Content-Type: application/json、それ以外はプレーンテキストになります。

状況	応答
プラグインが処理した	プラグインが返した文字列
プラグインが無効／このコマンドに対応していない	403（本文なし）
target に一致するプラグインが見つからない	400（本文なし）

• 使えるコマンドの一覧は プラグイン系API をご覧ください。

発話の受信(WebSocket)

• 表示用のデータをJSONとして受け取れます。

使用条件

• 特になし

• 送付方式：Websocket Text
• 送付先 :　ws://127.0.0.1:11901/
• ポート番号は前述のレジストリから取得してください

パラメータについて

• ゆかコネ開発時から拡張してきたこともあり、中身が整理されてません。
• でも、いますぐ使いたいという声もあるので、触りたい方はつかってみてください
• リファクタリングが進んだ暁には、このフォーマットは使わなくなるかもしれません

まず押さえるフィールド

タグ	内容
MsgID	この発話につくユニークなID。これをキーに管理してください
isDeleted	取り消された発話なら true。このときは表示を消してください
TextFixed	文章が確定したか
Text1 / Text6	母国語の文章（Text1＝上に表示する設定のとき、Text6＝下に表示する設定のとき）
Text2 ～ Text5	翻訳文の本体（翻訳1～翻訳4に対応）
Text1HTML ～ Text6HTML	ルビなどをHTMLに展開したもの。表示にはこちらを優先してください
Lang1 ～ Lang6	それぞれの言語名。空の枠は使われていません
KeepTime	表示を維持する残り秒数（後述）
SettingUpdate	設定の更新回数。数字が増えたら見た目の設定が変わっています
ShowCaptionMode	途中経過を表示しない設定なら 1
talkerID / talkerName	発話者のIDと名前
isOwnersTalkData	自分自身の発話なら true
InsertID	前後関係を表すID。このIDの次に続く文章という意味
AlreadyShown	すでに表示（確定）されたことがあるか

受け取ったあとの流れ

1. isDeleted が true なら、MsgID に対応する字幕を消してそこで処理を終えます（見た目の設定を読むより先に行ってください）。
2. SettingUpdate が前回と変わっていたら、フォント・色などの見た目を更新します。
3. MsgID をキーに文章を追加・更新します。TextFixed と ShowCaptionMode で表示するかどうかを決めます。
4. 表示する文章は Text1HTML～Text6HTML を優先して使います。

KeepTime の意味

• KeepTime は設定値そのものではなく、このデータを受け取った時点からの残り秒数です。
• 確定した字幕は2回届きます（母国語が確定したとき／翻訳が確定したとき）。2回目の KeepTime は、1回目からの経過時間が差し引かれています。
• 0 以下（本体は -1 を送ります）の場合は「時間で自動削除しない」という意味です。
• 実際に消えるタイミングは、isDeleted が true の別のデータで通知されます。

接続直後に1通届きます

• 接続すると必ず1通目が送られてきます。直前の確定した字幕、なければ本文が空の設定スナップショットです。
• 「つないだ直後に空の字幕が来る」のは仕様です。エラーではありません。

取り消し（isDeleted）のときは中身が違います

• isDeleted が true のときは、見た目の設定を含む全項目ではなく、必要最小限のフィールドだけが届きます（MsgID isDeleted InsertID talkerID talkerName SettingUpdate と、空になった Lang1～Lang6 Text1HTML～Text6HTML）。
• 見た目の設定を読もうとすると空になっているため、必ず isDeleted を先に判定してください。

全フィールドのサンプル（クリックで開きます）

        {
            "UpdateTranslation": false, //翻訳が更新されるとtrueになる
            "ShowCaptionMode": 0,//途中経過を表示しない設定なら1
            "Text1": "", //母国語(ユーザが上に表示すると指示するとこちらに入る)
            "Text2": "", //翻訳1
            "Text3": "", //翻訳2
            "Text4": "", //翻訳3
            "Text5": "", //翻訳4
            "Text6": "", //母国語(ユーザが下に表示すると指示するとこちらに入る)
            "Text1HTML": "",//母国語（ルビをHTML展開したもの）
            "Text2HTML": "",//翻訳1（同）
            "Text3HTML": "",//翻訳2（同）
            "Text4HTML": "",//翻訳3（同）
            "Text5HTML": "",//翻訳4（同）
            "Text6HTML": "",//母国語（ルビをHTML展開したもの）
            "Text1Clop": "",//母国語（Text1と同じ値が入ります）
            "Text2Clop": "",//翻訳1（Text2と同じ値が入ります）
            "Text3Clop": "",//翻訳2（同）
            "Text4Clop": "",//翻訳3（同）
            "Text5Clop": "",//翻訳4（同）
            "Text6Clop": "",//母国語（Text6と同じ値が入ります）
            "Lang1": "", //言語名
            "Lang2": "en",//言語名（翻訳1）
            "Lang3": "",//言語名（翻訳2）
            "Lang4": "",//言語名（翻訳3）
            "Lang5": "",//言語名（翻訳4）
            "Lang6": "",//言語名
            "LanguageNative": "ja",//母国語の言語名
            "KeepTime": 3.4260476667501467, //表示を維持する残り秒数
            "CaptureTimeMs": 1754630000000, //発話をとらえた時刻(UNIX時刻/ミリ秒)
            "SettingUpdate": 4829,//設定の更新次数。数字がUPしたら、ユーザが何か設定をかえた
            "LimitLine0": true,
            "LimitLine1": false,
            "LimitLine2": false,
            "ShowLangName": true, // ユーザが言語名表示を指示したらtrue
            "MsgID": "f4ad2560-11c0-494f-be04-5734bec5ea41", //文章に任意につくID
            "isDeleted": false,//この文章が消去されているものならtrue。trueになったら表示せず消すこと
            "isWaitClearing": false,//保持時間が過ぎるまで表示を切り替えない設定ならtrue
            "isOwnersTalkData": true,//自分自身の発話ならtrue
            "InsertID": "",//前後関係を表すID。ここに指示されたIDの次に続く文章
            "Alignment": "center",//文章の配置。left,center,right
            "AuthorName": "nao",
            "talkerID": "8141cf31-1685-4e88-97ce-9ae92981174b",//発話者に任意につくID
            "talkerName": "nao",//発話者名
            "BACKGROUND": "#00FF00FF",
            "FOREGROUND": "#FFFFFFFF",
            "DIVIDECOLOR": "#00FF00FF",
            "LINECOLOR": "#00FF00FF",
            "LINEWIDTH": 5.4123840909144327,
            "LINEADVHEIGHT": 1.8,
            "LINEHEIGHT": -0.5,
            "LINESPACE": -0.1,
            "LINESTYLE": "",
            "LINEBORDER": "",
            "WINDOWFRAMEHEIGHT": 181.0,
            "LINENUM": 2.2,
            "WSPORT": 11901,
            "Direction1": "ltr",
            "Direction2": "ltr",
            "Direction3": "ltr",
            "Direction4": "ltr",
            "Direction5": "ltr",
            "Direction6": "ltr",
            "FONT1NAME": "ＭＳ ゴシック",
            "FONT2NAME": "ＭＳ ゴシック",
            "FONT1SIZE": 70.9823527803947,
            "FONT2SIZE": 42.594463711823266,
            "FONT_M1_SIZE": 70.9823527803947,
            "FONT_M2_SIZE": 42.594463711823266,
            "FONT_M3_SIZE": 25.478836014663941,
            "FONT_M4_SIZE": 13.736800910932674,
            "FONT_M5_SIZE": 10.0,
            "FONT_M6_SIZE": 70.9823527803947,
            "FONT_M1_NAME": "ＭＳ ゴシック",
            "FONT_M2_NAME": "ＭＳ ゴシック",
            "FONT_M3_NAME": "ＭＳ ゴシック",
            "FONT_M4_NAME": "",
            "FONT_M5_NAME": "",
            "FONT_M6_NAME": "ＭＳ ゴシック",
            "Alignment1": "center",
            "Alignment2": "left",
            "Alignment3": "left",
            "Alignment4": "left",
            "TextFixed": false,
            "WINDOW_WIDTH_M": 800,
            "WINDOW_HEIGHT_M": 400,
            "WINDOW_LOCK_M": false,
            "BackColor": "#00FF00FF",
            "UseBaseColorSetting": false,
            "FORECOLOR_M2_L0": "#FFFFFFFF",
            "FORECOLOR_M2_L1": "#FFFFFFFF",
            "FORECOLOR_M2_L2": "#FFFFFFFF",
            "FORECOLOR_M2_L3": "#FFFFFFFF",
            "FORECOLOR_M2_L4": "#FFFFFFFF",
            "LINECOLOR_M2_L0": "#FF2600FF",
            "LINECOLOR_M2_L1": "#FF2600FF",
            "LINECOLOR_M2_L2": "#FF2600FF",
            "LINECOLOR_M2_L3": "#FF2600FF",
            "LINECOLOR_M2_L4": "#FF2600FF",
            "LINECOLOR_M3_L0": "#FF2600FF",
            "LINECOLOR_M3_L1": "#FF2600FF",
            "LINECOLOR_M3_L2": "#FF2600FF",
            "LINECOLOR_M3_L3": "#FF2600FF",
            "LINECOLOR_M3_L4": "#FF2600FF",
            "LINEWIDTH_L0": 5.4,
            "LINEWIDTH_L1": 5.4,
            "LINEWIDTH_L2": 5.4,
            "LINEWIDTH_L3": 5.4,
            "LINEWIDTH_L4": 5.4,
            "LINEWIDTH2_L0": 0.0,
            "LINEWIDTH2_L1": 0.0,
            "LINEWIDTH2_L2": 0.0,
            "LINEWIDTH2_L3": 0.0,
            "LINEWIDTH2_L4": 0.0,
            "BACKCOLOR_M0": "#00FF00FF",
            "BACKCOLOR_M1": "#00FFFFFF",
            "BACKCOLOR_M2": "#00FF00FF",
            "FORECOLOR_M0": "#00FF00FF",
            "FORECOLOR_M1": "#FFFFFFFF",
            "FORECOLOR_M2": "#FFFFFFFF",
            "LINECOLOR_M1": "#FF2600FF",
            "LINECOLOR_M2": "#FF2600FF",
            "LINECOLOR_M3": "#FF2600FF",
            "LINEWIDTH_M1": 5.4123840909144327,
            "LINEWIDTH_M2": 5.4123840909144327,
            "LINEWIDTH_M3": 0.0,
            "AlreadyShown": false,
            "Neo.WebSocket": "11901",
            "Neo.HTTP": "11900",
            "Plugin_OCTemplateGen.Port.WebSocket": "54000",
            "Plugin_PlayVoice.VoiceList": "[\"つくよみちゃん-れいせい/COEIROINK\",\"MANA-のーまる/COEIROINK\",\"おふとんP-のーまる/COEIROINK\",\"ディアちゃん-のーまる/COEIROINK\",\"アルマちゃん-のーまる/COEIROINK\",\"つくよみちゃん-おしとやか/COEIROINK\",\"つくよみちゃん-げんき/COEIROINK\",\"れみ♀-キュート/LMROID\"
            ]",
            "Plugin_TransSrv.Port.HTTP": "8080",
            "Plugin_TransSrv.Port.WebSocket": "52000"
    }

発話の受信(WebSocket,シンプル)

• 表示用のデータをJSONとして受け取れます。

使用条件

• ゆかコネNEO v2.0～

• 送付方式：Websocket Text
• 送付先 :　ws://127.0.0.1:11901/text
• ポート番号は前述のレジストリから取得してください

パラメータについて

• 前述のAPIと異なり、内容がかなり絞られています

Query意味特性

    {
    "textList": {
        "ja": "今日はよい天気です",
        "en": "Good weather today"
    },
    "fixedText": true,
    "talkerID": "8141cf31-1685-4e88-97ce-9ae92981174b",
    "talkerName": "なお",
    "MessageID": "f72e0ee4-a8f1-4bfa-8a0c-773d348b8375",
    "isAlreadyShown": false,
    "isOwnersTalkData": true,
    "isDeleted": false
    }

タグ	内容
textList	発話もしくは翻訳文のリスト（keyは言語名、dataは文章）
fixedText	文章が確定したか
talkerID	発話者のユニークなID
talkerName	発話者名
MessageID	この発話に対するユニークなID
isAlreadyShown	既に表示（確定）されたことがあるか
isOwnersTalkData	自分自身の発話か
isDeleted	文章が取り消されているか

• 途中経過を送るかどうかは、見た目の微調整にある「過程を送る」に左右されます。
• 未確定の状態（発話途中）はfixedText=falseで送られます
• 確定した場合、まず母国語が確定した時点で一度送付されます。この時点ではほかの翻訳文は空欄です。
• その後、翻訳が確定したら、その文が送付されます。
• 翻訳はエンジンや設定によって並列処理しているので何度か通知が来ます。
• 基本的にはMessageIDで文章を個体識別し、最新の文章を採用してください。
• 編集者により文が取り消された場合、isDeleted=trueとなります。

textList はキーの有無が変わります

• textList には、その時点で確定している言語だけが入ります。翻訳がまだ終わっていない言語は、キーそのものが無いか、空文字になります。
• 「キーが無いから翻訳しない設定なのだ」とは判断しないでください。
• MessageID ごとに、届いた最新のデータで全体を置き換えるのが安全です。

発話の受信(WebSocket,文のみ)

• 表示用のデータをテキストとして受け取れます。

使用条件

• ゆかコネNEO v2.0.99～

• 送付方式：Websocket Text
• 送付先 :　ws://127.0.0.1:11901/textonly
• ポート番号は前述のレジストリから取得してください

パラメータについて

• 文のみです

Query特性

    今日はよい天気です

• 文しかきません。
• アップデートされた分や削除された分は届きません。

届く条件が絞られています

• 次のすべてを満たしたときだけ送られます。
  • 文章が確定している
  • まだ表示されたことがない（再表示ではない）
  • 取り消されていない
  • 翻訳の更新による再送ではない
• 母国語だけが届きます。翻訳文は届きません。 翻訳文も欲しい場合は /text を使ってください。

文字を送る(WebSocket)

• 外部の音声認識ツールなどから、認識結果をゆかコネNEOへ流し込めます。

使用条件

• 特になし

• 送付方式：Websocket Text
• 送付先 :　ws://127.0.0.1:11901/

送る文字列	意味
今日はよい天気です	確定した文章として取り込みます
@今日はよい	先頭に @ を付けると、未確定（途中経過）として取り込みます
@$ja	認識する言語を指定します
@$ja-en	認識する言語と翻訳先を指定します

• 空白だけの文字列は取り込まれません。
• HTTPの /api/input と違い、つなぎっぱなしにして連続で流し込めるので、途中経過を細かく送りたい場合に向いています。
• ほかの端末（LAN）から送るときは、接続先の URL に ?token=… が要ります（アクセス制御について）。

JSON 形式で送る

使用条件

• ゆかコネNEO v3.0.0～

• 上の文字列の代わりに、JSON オブジェクトを1つ送ることもできます。{ で始まり } で終わるものは JSON として読みます。
• 項目名は、このページの「入力の受付(拡張)」の POST と同じ（Text fixedText textID UserID TalkerName ignorePlugin Morph forceInput）に、認識した言語 Language を足したものです。
• 文ごとに textID と話者を持てるので、2本のマイクの途中経過を同じ接続で流しても混ざりません。ブラウザ音声認識・オフライン音声認識も、この形式で送っています。

JSON

{"Text":"今日はよい","fixedText":false,"textID":"a1b2c3","Language":"ja"}

• 途中経過は fixedText を false にして同じ textID で送り、最後に true で確定させます。
• 1件は 64KB まで、本文は 4000 字までです。
• /api/input と違い、API から来た文としては扱われず、音声認識の文と同じように処理されます。

2人目の話者として送る

• 送付先 :　ws://127.0.0.1:11901/2nd

送る文字列	意味
$name$なお	2人目の話者の表示名を設定します
こんにちは	2人目の話者の発話として取り込みます

• 1台のパソコンで2人分の字幕を出したいときに使います。

そのほかの接続先

/speech /translate /llm は、ゆかコネNEOがブラウザの読み上げ・翻訳・AI機能とやりとりするために使っている接続先です。外部ツールから使うことは想定していません。

字幕テンプレートを自作する

• 配信ソフトのブラウザソースで開くURLと、そのオプションについて説明します。

使用条件

• 特になし

ブラウザソースのURL

http://<IPアドレス>:<HTTPポート>/<テンプレートのフォルダ>/<HTMLファイル>?port=<WebSocketポート>

• 「レイアウトデザインの選択」画面に表示されているアドレスがこの形です。ダブルクリックでコピーできます。
• 既定のテンプレートは MultiLang_R/MultiLang_R.html です。
• テンプレートの実体があるフォルダは、レジストリの LayoutDir から取得できます。「レイアウトデザインの選択」画面の「テンプレフォルダを開く」でも開けます。

URLに付けられるオプション

クエリ	意味
?port=	テンプレートが接続するWebSocketポートの指定。通常はゆかコネNEOが自動で付けます
?solo=native	母国語だけを表示します
?solo=trans1 ～ ?solo=trans4	翻訳1～翻訳4のどれか1つだけを表示します
?view=me / ?view=other	左右2分割のテンプレート（トークセッション横並び、ゲーム風横ならべなど）で、どちら側を表示するかの指定

例）翻訳1だけを別のブラウザソースに出す

    http://localhost:11900/MultiLang_R/MultiLang_R.html?port=11901&solo=trans1

言語ごとに別のソースとして取り込む

?solo= を使うと、言語ごとに位置やサイズを別々に調整できます。同じことは「レイアウトデザインの選択」画面の「応用パターン（１言語ごとの取り込み）」からも行えます。

データの受け取り方

• テンプレートは ws://127.0.0.1:<WebSocketポート>/ に接続して、前述の「発話の受信(WebSocket)」のデータを受け取ります。
• 処理の流れは「受け取ったあとの流れ」の4ステップと同じです。
• ゆかコネNEOは port.js にポート番号を書き出しているので、テンプレート側からはそれを読み込んで使うこともできます。

テンプレートの自作はサポート対象外です

• 標準のテンプレートを書き換えた場合、アップデートで上書きされることがあります。自作したものは別のフォルダにコピーして使ってください。
• データの形式は予告なく変わることがあります。

AIアシスタント（MCP）からゆかコネを操作する

使用条件

• ゆかコネNEO v3.0.7～（「AI クライアントの設定」のページは v3.0.11～）
• Streamable HTTP に対応した MCP クライアント（Claude Code・VS Code・Cursor・Claude Desktop・Codex CLI など）

• MCP サーバー プラグインを使うと、AI アシスタント（MCP 対応のアプリ）から、ゆかコネNEO の状態を調べたり、読み上げ・字幕・翻訳などを頼んだりできます。
• 既定ではこの PC からだけつながり、AI に使わせるのは何も変えない（読むだけの）機能だけです。配信に乗る機能や利用料のかかる機能は、自分で選んだものだけが使えるようになります。

つなぎ方

1. 上のタブの 「プラグイン」 を開き、一覧の 「MCP サーバー」（分類は「API・ツール拡張」）を 「使う」 にします。待ち受けが始まります。
2. 歯車のボタンで設定画面を開き、「AI クライアントの設定」 のページを開きます。
3. 使っている AI クライアントの欄で 「例をコピー」 を押し、そのクライアントの設定に貼り付けます。
4. AI クライアントを起動し直すと、ゆかコネNEO のツールが使えるようになります。

• つなぐ先は既定で http://127.0.0.1:8766/mcp です（「接続」のページの「待ち受け先」「ポート」「パス」で変えられます）。
• 「AI クライアントの設定」のページには、次のクライアントの設定例が並びます。例は編集中の値で作られます（待ち受けが変わるのは「OK」か「適用」を押したときです）。

クライアント	書く場所
Claude Code	端末（PowerShell など）で、表示された1行（claude mcp add --transport http ync-neo …）を打ちます。Claude Code の中で /mcp と打つと、つながったか確かめられます
VS Code (GitHub Copilot)	作業フォルダの .vscode/mcp.json
Cursor	ホームフォルダか作業フォルダの .cursor/mcp.json
Claude Desktop	「設定」→「開発者」→「構成を編集」で開く claude_desktop_config.json。書いたら Claude Desktop をいったん終了して起動し直します。中継に mcp-remote を使うので、Node.js（npx）が要ります
Codex CLI	ホームフォルダの .codex/config.toml の最後
その他のクライアント	つなぐ先の URL と、要るときはヘッダーを設定します

例）VS Code の .vscode/mcp.json（この PC からだけつなぐとき）

{
  "servers": {
    "ync-neo": {
      "type": "http",
      "url": "http://127.0.0.1:8766/mcp"
    }
  }
}

接続キー

• この PC からだけつなぐ既定の設定では、接続キーは要りません。
• 次のときは接続キーが要ります。「接続」のページの 「接続キーを作ってコピー」 で作ってください。
  • 「待ち受け先」にこの PC の IP アドレスを書いて、LAN の別の PC から使うとき
  • 「接続を許すページ」にインターネット上のページ（https://～）を書いたとき
  • 「この PC からの接続にも接続キーを求める」 を ON にしたとき
• クライアントには Authorization: Bearer <接続キー>（または X-API-Key: <接続キー>）で渡します。
• 「AI クライアントの設定」の例では、キーは <接続キー> という仮の文字で表示されます。「キー入りでコピー」 を押すと、本物のキーに差し替えてクリップボードへ写します（画面には出しません）。貼り付けたら、別の文字をコピーするなどしてクリップボードを空にしてください。
• 「接続キーを作ってコピー」で作り直すと、前のキーは使えなくなります。

AI に使わせる機能を選ぶ

• 「使えるツール」のページの 「出すツール」 で選びます。「状態の確認」は常に出します。

ツール	既定	注意
状態の確認・プラグインの一覧・言語の判定	出す	読むだけ
AI クライアントへの問い合わせ・利用者への質問	出す	つないだ側の AI・画面を使う
翻訳	出さない	翻訳エンジンの利用料がかかることがある
本体の AI に問い合わせ	出さない	本体に設定した AI キーの利用料がかかる
読み上げ・読み上げの停止	出さない	配信に声が乗る／止まる
字幕の送信	出さない	配信に字幕が乗る。読み上げ系のプラグインが有効なら読み上げられる
他のプラグインへの命令	出さない	「命令を送ってよいプラグイン」にタグを書いたプラグインだけ。最も強い権限

• 各プラグインの「状態の確認」など、何も変えない操作は、選ばなくても出します（「他のプラグインの「読むだけ」の操作は選ばなくても出す」で止められます）。状態を変える操作は、「出すツール」で選んだものだけ出します。
• 「承認」と付いた操作（シーンの切り替えや試し読み、本体の動作チェックなど、配信に見えるもの）は、AI が呼ぶたびに ゆかコネNEO の画面で許可を求めます。60 秒以内に答えないと断ります。
• 「本体の AI に問い合わせ」で使うモデルは、設定画面の「本体の AI のモデル」で決めます。AI クライアントからは変えられません。

ブラウザのページからつなぐとき

• ブラウザ上のヘルプデスクなどから直接つなぐときは、「ブラウザと上限」のページの 「接続を許すページ (Origin)」 に、そのページのアドレスを 1 行に 1 つ書きます（例: この PC のヘルプデスクなら http://localhost:3210）。ポートまで同じものだけ通します。
• この PC のページだけなら接続キーは要りません。インターネット上のページを書くと接続キーが必須になります。
• 「許可していないページから来たら、その場で訊く」 が ON（既定）のときは、許可していないページから来たときに「MCP サーバー: 接続の許可」の窓が出ます。心当たりがあれば 「許可する」 を押すと、そのままつながり、「接続を許すページ」に足されます。60 秒で自動的に断ります。

つながらないとき

• 設定画面の 「接続の記録」 のページに、つながった・断った（理由つき）・呼ばれた記録が新しい順に出ます。ブラウザのページ側には断られた理由が見えないので、まずここを見てください。
• 断ったページは、記録の画面の 「（ページ） を許可する」 で許可に足せます。
• 「停止しています」と出るときは、プラグイン一覧で「使う」になっているか確かめてください。

AI に任せる範囲は必要なだけに

• 配信に乗る機能（読み上げ・字幕）や、利用料のかかる機能（翻訳・本体の AI）は、使うときだけ ON にしてください。
• 接続キーは画面・設定ファイル・ログには出しません。知られたときは「接続キーを作ってコピー」で作り直してください。