N.E.K.O.REST API与WebSocket协议速查26个路由端点与消息类型完全参考手册【免费下载链接】N.E.K.OA catgirl who lives with you in real time — reaching out first, sharing your media, and actually getting things done, powered by an embodied emotional engine.❤️一只会主动找你玩的 AI 猫娘。项目地址: https://gitcode.com/gh_mirrors/ne/N.E.K.ON.E.K.O 是一只会主动找你玩的 AI 猫娘catgirl companion它通过一个本地 FastAPI 主服务对外提供 REST API 与 WebSocket 实时通信协议。本文是面向新手的N.E.K.O REST API 与 WebSocket 协议速查手册用表格和最少代码帮你快速搞清楚哪些 HTTP 端点能做什么、客户端/服务器之间流动哪些消息类型、以及连接生命周期该怎么走。一、5分钟理解 N.E.K.O 的通信架构N.E.K.O 的通信面由三类服务组成服务默认地址给谁用主服务REST WebSockethttp://127.0.0.1:48911网页 / Electron / 手机客户端Memory Serverhttp://127.0.0.1:48912内部记忆生命周期与召回Agent Serverhttp://127.0.0.1:48915内部Agent 任务执行三个关键认知新手最容易踩坑的点⚠️没有统一鉴权层。主 API 没有全局 Token敏感路由如/api/tools、/api/capture各自强制环回loopback访问。切勿把48911端口暴露到公网或不受信任的内网。REST 路由主要服务 N.E.K.O 自己的 UI只有少数几个工具注册、云存档、抓取桥是稳定的本地集成契约。WebSocket 是打包 UI 协议而非独立版本化的公共标准标记为 internal 的消息族可能随第一方界面变化。完整边界说明见 docs/api/index.md。二、REST 路由速查表26 个端点分组一览所有路由挂载在主服务上源码位置见 app/main_server/web_app.py。下面按用途分组速查1. 文档化的集成契约本地插件/伴侣进程可用前缀用途安全边界/api/tools注册模型可调用的 HTTP 回调工具仅环回回调 URL 也必须是环回地址/api/cloudsave按角色单位的存档上传/下载破坏性数据操作需明确用户行为/api/capture第一方 Electron/视觉小说抓取桥仅环回/api/tools有 4 个端点POST /api/tools/register、POST /api/tools/unregister、POST /api/tools/clear、GET /api/tools。注册时同名工具会被替换响应中的ok字段区分完整成功、部分成功failed_roles与全部失败详见 docs/api/rest/tools.md。2. 第一方应用路由服务 N.E.K.O 自身界面前缀管什么/api/config供应商配置、偏好设置、连通性测试/api/characters角色/人格/卡片/语音/头像绑定最大的一个路由/api/live2d、/api/model/vrm、/api/model/mmd、/api/model/pngtuber四类虚拟形象模型与表情映射/api/vmc给 VRM 的本地 OSC/UDP 动作输出/api/memory近期记忆文件、审查/设置、重命名/api/agentAgent 任务状态、开关、诊断代理/api/steam/workshopWorkshop 浏览、暂存、发布、订阅/api/music、/api/jukebox音乐搜索播放代理、曲库与动作库/api/game、/api/galgame、/api/icebreaker小游戏状态、视觉小说回复选项、新手引导/api/proactive主动聊天模式与设置猫娘先找你的开关/apisystem启动、提示词、截图、Steam 与诊断例如角色路由就包含创建/删除/重命名角色POST /api/characters/catgirl、头像绑定PUT /api/characters/catgirl/l2d/{name}、语音克隆POST /api/characters/voice_clone等 50 端点完整清单见 docs/api/rest/characters.md。3. 内部/未版本化路由第三方不要依赖/api/storage/location首次启动存储选择、/api/avatar-drop、/api/card-assist、/api/auth凭据敏感、/api/debug、/health等。这些会随 UI 一起演进除非你同时锁定 N.E.K.O 版本否则别对它们做集成。4. 响应格式小贴士响应外壳因路由而异FastAPI 校验类错误常见detail字段应用路由多返回success/error/code。务必按机器可读的 code 分支而不是解析英文消息。常见内容类型包括 JSON、上传用的multipart/form-data、语音预览的音频流、以及 WebSocket 上的二进制音频帧。三、WebSocket 连接速查一条路由走天下主应用只暴露一条应用级 WebSocket 路由ws://127.0.0.1:48911/ws/{角色名}角色名需 URL 编码有可信反代终结 TLS 时用wss://。连接建立的 4 步服务器校验路径上的角色名是否在进程内会话管理器中角色未知 → 可能先发catgirl_switched提示回退角色然后关闭连接角色有效 → 连接安装到该角色的会话管理器内部 UUID 不会作为确认帧下发立即可用greeting_check等控制动作但发送会话媒体前必须先start_session。多连接时只有最新的连接 UUID 有效旧连接再发帧会收到CHARACTER_SWITCHING_TERMINAL并被断开——这就是多窗口靠项目内跨页同步层、而不是各自竞争主套接字的原因。四、帧模型与会话生命周期新手必看客户端命令UTF-8 JSON 文本帧顶层字段为action服务器事件UTF-8 JSON 文本帧顶层字段为type麦克风音频首选二进制帧ASCIINEKO 小端 uint32 采样率16000/48000 单声道小端 PCM16TTS 音频是例外先audio_chunkJSON 头紧跟一个二进制帧。会话生命周期一图流文字版socket open ├─ voice_input_control(lease_sync) ← 音频客户端强烈建议先同步麦克风租约 ├─ start_session → session_preparing → session_started或 session_failed ├─ stream_data / avatar_interaction / 控制事件 ├─ pause_session 或 end_session → 供应商会话结束socket 保持打开 └─ socket 关闭 → 清理当前供应商会话关键消息只有几条记住它们就能写出可用的客户端方向消息作用客户端start_session开启会话input_type可选audio/screen/camera/text/avatar_drop_image/user_image客户端stream_data发文本/图片/音频数据可带request_id追踪回合客户端end_session/pause_session结束或暂停当前供应商会话客户端ping→pong应用层心跳保活服务器session_started唯一可靠的可以开始流式发送信号服务器gemini_response助手文本流式输出名字是历史遗留多供应商共用服务器status错误信封message里还套着一层 JSON{ code, details? }错误处理是新手最大的坑status事件的message是JSON 编码过的字符串需要再解析一次。已知码包括INVALID_INPUT_TYPE、UNKNOWN_ACTION、SERVER_ERROR、VOICE_INPUT_CONTROL_REJECTED、VOICE_INPUT_LEASE_REQUIRED、CHARACTER_SWITCHING_TERMINAL等集合会增长客户端请对未知码做通用兜底。五、消息类型完整清单客户端 → 服务器action类别action备注会话start_session、end_session、pause_session生命周期三件套输入stream_data文本 / 图片 data URL / PCM 音频数组兼容格式麦克风治理voice_input_controlevent含lease_sync、hard_mute、focus_suppress、game_takeover等 7 种交互avatar_interaction对虚拟形象的轻触/手势完成时回avatar_interaction_ackUI/生命周期ping、language_update、greeting_check、cat_greeting_check、goodbye_state、voice_play_start、voice_play_end其中播放边界事件用于主动聊天仲裁生成完成 ≠ 播放完成抓取桥内部capture_bridge_status、capture_bridge_response、screenshot_response第一方抓取能力遥测尽力而为telemetrykind 为counter/histogram/event不要把用户文本塞进去voice_input_control的lease_generation在同一连接内必须单调递增、重连后清零一旦发出过显式控制消息哪怕是错的连接就永久走严格路径旧版 generation-0 兼容租约不再可用。engaged的语义也很微妙只有字面量false表示不抢占麦克风省略时按旧版客户端兼容、默认抢占。服务器 → 客户端type类别type作用会话session_preparing、session_started、session_failed、session_ended_by_server、catgirl_switched、pong生命周期与角色切换文本/音频gemini_response、audio_chunk文本流与语音块后者后跟一个二进制帧恢复response_discarded、user_transcript、user_activity、auto_close_mic、repetition_warning重试回滚、实时转写、打断协调、静音超时状态/显示status、expression、focus_state、focus_charge、focus_thinking、topic_hint、cancel_topic_hint、reload_page驱动表情、专注态发光、配置变更重载等第一方工作流agent_notification、request_screenshot、mini_game_invite_options、music_play_url等非稳定外部契约随 UI 演进客户端必须安全忽略未知type这样新增的 UI 事件才不会弄崩你的程序。六、音频流协议N.E.K.O 语音交互的心脏N.E.K.O 的实时语音是双向二进制帧设计方向首选格式客户端 → 服务器NEKO魔数 小端采样率 单声道 PCM16每帧 10–32ms最长 120ms客户端 → 服务器兼容JSON 数组形式的 PCM16 采样值不是 base64服务器 → 客户端audio_chunk头 一个二进制帧通常为 48kHz PCM16三个实用要点等session_started再发音频session_preparing不代表就绪服务器语音没有audio_end帧用speech_id关联所有块打断时前端丢弃迟到块打断barge-in依赖供应商用户活动事件 客户端speech_id过滤——已经发出去的帧收不回来所以永远按 speech_id 过滤不要假设下一个二进制帧就一定可播放。完整帧布局表见 docs/api/websocket/audio-streaming.md。七、安全边界与最佳实践清单 端口48911只留在回环地址要跨机访问请上带鉴权和 Origin 限制的反代 不要把遥测维度、本地抓取响应、角色名当成可信输入 供应商 API Key 由配置系统管理见 docs/config/不走 API Bearer Token 做长期集成的稳定扩展面是插件系统plugin/而不是直接依赖主服务路由只有当插件需要暴露模型可调用回调时才用/api/tools契约 内部服务Memory/Agent Server仅供主服务间通信调试 N.E.K.O 本身时再看 docs/api/memory-server.md 与 docs/api/agent-server.md。八、延伸阅读官方协议文档地图主题文档API 总览与兼容边界docs/api/index.mdWebSocket 协议连接/会话/安全docs/api/websocket/protocol.md消息类型全清单docs/api/websocket/message-types.md音频流细节docs/api/websocket/audio-streaming.mdREST 分路由手册21 篇docs/api/rest/三服务器架构docs/architecture/three-servers.md一句话总结N.E.K.O 的对外协议 26 个以/api为主的 REST 路由分组 一条ws://127.0.0.1:48911/ws/{角色名}应用套接字抓住start_session → session_started → stream_data这条主线再按机器可读的status.code处理异常你就已经能驱动这只猫娘的绝大部分能力了。【免费下载链接】N.E.K.OA catgirl who lives with you in real time — reaching out first, sharing your media, and actually getting things done, powered by an embodied emotional engine.❤️一只会主动找你玩的 AI 猫娘。项目地址: https://gitcode.com/gh_mirrors/ne/N.E.K.O创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考