API リファレンス
N.E.K.O. のメイン FastAPI サーバーは既定でポート 48911 を使用します。ここでは現在のソースツリーに存在するルートを記載していますが、すべてが安定した公開 API、またはリモート公開に安全な API という意味ではありません。
互換性の境界
| サーフェス | 想定利用者 | 互換性の想定 |
|---|---|---|
| ランタイムツール API | ローカルプラグインとコンパニオンプロセス | 文書化されたローカル統合契約 |
| メイン WebSocket プロトコル | N.E.K.O. の Web、Electron、モバイルクライアント | 文書化されたクライアントプロトコル。内部メッセージはファーストパーティー UI と共に変更される場合がある |
| クラウドセーブ API | ローカルデータ管理クライアント | 文書化された破壊的データ操作。明示的なユーザー操作が必要 |
| その他のメインサーバー REST ルート | N.E.K.O. のファーストパーティーページと貢献者 | 実装向け。UI と共に変化し、汎用公開 Web API ではない |
| メモリサーバーとエージェントサーバー | メインサーバーと内部サービス間 | 内部専用。N.E.K.O. 自体のデバッグ以外ではメインサーバー経由で使う |
N.E.K.O. は現在、全体的な後方互換性を保証する独立バージョン付き HTTP API を公開していません。安定した拡張面はプラグインシステムです。モデル呼び出し可能なコールバックを公開する必要がある場合だけランタイムツール契約を使ってください。
ベース URL とセキュリティ
http://127.0.0.1:48911メイン API 全体を覆う認証レイヤーはありません。/api/tools や /api/capture など一部の機密統合ルートはループバック制限を実装していますが、多くのファーストパーティー UI ルートにはありません。ポート 48911 を信頼できない LAN やインターネットへ公開しないでください。プロバイダー API キーは設定システムで管理され、API Bearer Token ではありません。
明記されていない限り、パス末尾に / はありません。
メインサーバー REST ルート
文書化された統合とデータ操作
| ルーター | プレフィックス | 境界 |
|---|---|---|
| ランタイムツール | /api/tools | ループバック専用のプラグインコールバック登録 |
| クラウドセーブ | /api/cloudsave | キャラクターユニットのアップロード／ダウンロード。破壊的操作を含む |
| キャプチャブリッジ | /api/capture | ループバック専用のファーストパーティー Electron/GalGame ブリッジ |
ファーストパーティーアプリケーションルート
以下のページは貢献者や代替ローカルクライアントに有用ですが、主に N.E.K.O. 自身の UI が利用します。
| ルーター | プレフィックス | 範囲 |
|---|---|---|
| 設定 | /api/config | プロバイダー設定、ユーザー設定、接続テスト |
| キャラクター | /api/characters | キャラクター、ペルソナ、カード、音声、アバター操作 |
| Live2D | /api/live2d | Live2D モデルと感情マッピング |
| VRM | /api/model/vrm | VRM モデル、設定、アニメーション、表情 |
| VMC モーション出力 | /api/vmc | active VRM motion の local OSC/UDP 出力 |
| MMD | /api/model/mmd | MMD モデルとモーション管理 |
| PNGTuber | /api/model/pngtuber | PNGTuber モデル管理 |
| メモリ | /api/memory | 直近メモリファイル、レビュー/設定、名前変更、旧ストレージ整理。recall は内部 /query_memory route を使用 |
| エージェントプロキシ | /api/agent | メインサーバープロキシ、タスク状態、フラグ、診断 |
| Steam Workshop | /api/steam/workshop | 閲覧、ステージング、公開、購読 |
| 音楽 | /api/music | 音楽検索と再生プロキシ |
| ジュークボックス | /api/jukebox | 楽曲とアクションライブラリ |
| ミニゲーム | /api/game | ミニゲームの状態と操作 |
| GalGame | /api/galgame | GalGame の返信候補生成 |
| アイスブレイク | /api/icebreaker | 新規ユーザーのオンボーディング |
| プロアクティブチャット | /api/proactive | プロアクティブチャットのモードと設定 |
| システム | /api | 起動、プロンプト、スクリーンショット、ユーティリティ、Steam、診断 |
WebSocket
メインアプリケーションソケットは ws://127.0.0.1:48911/ws/{character_name} です。
| ページ | 内容 |
|---|---|
| プロトコル | 接続ライフサイクル、セッション操作、セキュリティ境界 |
| メッセージタイプ | クライアント操作、入力データ、サーバーイベント |
| オーディオストリーミング | JSON PCM 入力とバイナリフレームのサーバー音声出力 |
内部および未バージョン化サーフェス
メインサーバーには、公開リファレンスページを意図的に持たない次のファーストパーティー実装ルートもあります：
/api/storage/location— 初回起動時の保存先選択、移行、ディレクトリ選択、再起動、保持ソースのクリーンアップ。/api/avatar-drop— コンポーザー用ドキュメント解析補助。出力は現在のファーストパーティー UI に従う。/api/card-assist— 現在のプロンプトと設定済み LLM プロバイダーに結合したキャラクターカード生成／推敲。/api/auth— ローカル Cookie と QR ログイン状態。互換エンドポイントを含み、認証情報を扱う。/api/debug— 変更され得る診断スナップショットとブラウザヘルス報告。/health— ランチャー／プロセス用の軽量ヘルスプローブ。/api/beacon/shutdown— ブラウザモードのライフサイクル制御。アプリ統合用ではない。/marketと/market/{path}— ユーザープラグインサーバーへの不透明な同一オリジンリバースプロキシ。スキーマはメイン API の所有物ではない。
一致する N.E.K.O. バージョンも管理しない限り、これらに対するサードパーティー統合を構築しないでください。
内部サービス API
| サーバー | 既定アドレス | 境界 |
|---|---|---|
| メモリサーバー | http://127.0.0.1:48912 | 内部メモリライフサイクル、レンダリング、検索 |
| エージェントサーバー | http://127.0.0.1:48915 | 内部エージェント実行と ZeroMQ トランスポート |
レスポンスとコンテンツタイプ
レスポンス形式はルーターごとに異なります。FastAPI/Pydantic の検証は通常 detail を使いますが、アプリケーションルーターには success、error/code、メッセージフィールドを返すものもあります。各ページの契約に従い、英語メッセージではなく機械可読コードで分岐してください。
主な形式は JSON、アップロード用 multipart/form-data、音声プレビューの音声レスポンス、サーバー音声用の WebSocket バイナリフレームです。