接口说明 / 到口数字生命对接

到口数字生命 · 中国宇宙研究院 App 对接说明

项	值
受众	中国宇宙研究院（App 合码；勿交南昌旧人）
日期	2026-10-20（Asia/Shanghai）
作者	Grok Bot
产品名	到口数字生命（全文统一；禁止写「到口数字生命」「到口数字生命」）
主坐席	门铃号 1000（到口）

本文只写现网已核实能力与路径；不含密码/密钥明文。联调以公网现网为准。

0. 一句话定位

到口数字生命 = 门铃号 1000 = 平台全能助手 / 数字生命入口。
App 主对接：私聊 1000（自有 IM，已去融云）。

门铃号	角色	App 是否主对接
1000	到口数字生命（全能：不限平台、不限问题）	是 · 主对接
9999	到门口客服（只答到门口）	否
10000	门铃客服（只答门铃）	否
1	中国宇宙研究院客服（只谈研发）	否

禁止：把 9999 / 10000 / 1 当全能；App 调内部桥；接融云。

1. 文字对话（自有 IM · App 主路径）

1.1 Base 与鉴权

项	值
Base	`https://api.menling.com`
勿用	`api.menkou.com`（业务 API，不是发信路径）
鉴权	`Authorization: Bearer <JWT>`（与现网门铃/到门口登录 JWT 一致；亦可现网 Cookie）
Content-Type	`application/json; charset=utf-8`

统一响应壳（与现网 IM 一致）：{ "code": 200, "msg": "ok", "result": "..." }。
未登录常见：code 为 "10000"，msg: "Not loged in."（公网未带 JWT 已实测）。

1.2 发私聊（触发自动回复）

POST https://api.menling.com/message/send_private
Authorization: Bearer <JWT>

{
  "destId": "1000",
  "content": "用户说的话",
  "contentType": 1
}

字段	说明
`destId`	对方门铃号字符串；到口固定 `"1000"`（也可用现网 N3d 密文）
`contentType`	`1`=文本；`3`=图片（已入桥，见 §5）
返回	发信接口立刻返回，不挡自动回复；消息入库 `source=menling_im`

公网烟测（2026-10-20）：未登录 POST → HTTP 200 + Not loged in.（路由通）。

1.3 拉私聊（拿自动回复）

GET https://api.menling.com/message/pull_private?peerId=1000&limit=50&lastId=
Authorization: Bearer <JWT>

字段	说明
`peerId`	与发信同一坐席 → `1000`
`lastId`	增量游标；首拉可空
回复来源	自动回复一般 `source=kefu_ownim`

也可继续用现网推送；推送未到时以 pull_private 为准。

1.4 现网时延（热修后 · 参考）

时延以现网热修后为准（勿再写「约 1 分钟」）。

场景	桥端到端（约）
冷知识（必走模型）	6.5–7.5 s
词库 / 缓存命中（如陶瓷）	约 1–3 s
短招呼「你好」	约 1–2 s

App 建议：发信后轮询 pull_private，首轮可 1–2 s 起，冷路径留到约 10–15 s。

1.5 联调步骤

登录拿 JWT。
POST send_private，destId=1000，发任意问题。
轮询 GET pull_private?peerId=1000。
期望：坐席 1000 → 用户的回复。

2. 到口数字生命管理入口（H5）

IM 聊天框「到口数字生命」按钮打开：

https://my.menkou.com/muser/aitwin/index

未登录 → 302 到登录页（公网已实测路由通）。
登录后进入到口数字生命管理页（Yii1 AitwinController + yii1-bridge）。
App 展示文案请写 「到口数字生命」，不要写「到口数字生命」。
技术路径名仍为 /muser/aitwin/...（历史代码名，勿改公网 URL）。

2.1 登录态接口（需站内登录 Cookie；同站 POST）

Base：https://my.menkou.com/muser/aitwin/

方法	路径	用途
GET	`/index`	管理页 HTML
GET/JSON	`/state`	当前用户分身状态、钱包、配置
POST	`/open`	开通分身
POST	`/save`	保存：`name` / `intro` / `tone` / `faq`(JSON) / `mode` / `offline_delay` / `learn_consent` / `cs_spend`
POST	`/toggle`	`on=0\|1` 开关分身
POST	`/learn`	从近 90 天自己发出的文字回复学习语气
POST	`/preview`	试聊（不扣算力，日限）`q=`
POST	`/signin`	签到领算力
POST	`/claimOrders`	领取订单结算算力
POST	`/transferLookup`	转账前查对方门铃号
POST	`/transfer`	转账（需 `to` + `confirm_to` + `amount`）
GET	`/ledger`	流水 / 订单
POST	`/pay`	充值下单（微信/支付宝渠道由服务端配置）
GET	`/payQuery`	查单 `no=`
POST	`/embedSave`	企业挂件：域名白名单、颜色、标题、换 key
GET	`/inbox`	挂件会话列表
GET	`/inboxConv`	会话消息 `id=`
POST	`/inboxReply`	人工回复（该会话转人工）
POST	`/inboxHuman`	`human=0\|1` 交还分身 / 转人工

说明：

当前没有单独「形象 URL / TTS 音色 ID」字段；分身可配 名称、简介、语气 tone、FAQ、模式。
App 一期若只做「跟到口聊天」：不必接上述 H5 API，用 §1 私聊 1000 即可。
管理分身可 WebView 打开 H5，或按上表逐步原生化。

2.2 公开接口（企业挂件 / 服务端 REST · 非 App 主路径）

方法	路径	说明
GET	`/widget?k=<site_key>`	返回挂件 JS
GET	`/chat?k=...`	挂件 H5 聊天页
POST/GET	`/wask`	挂件提问（`k`/`vid`/`tk`/`q`）
GET	`/wpoll`	挂件轮询消息
POST	`/api`	服务端 REST：头 `X-Aitwin-Key` + `X-Aitwin-Secret`；`action=ask\|messages`，`user_id`，`q`/`since`
GET	`/doc`	接入说明 HTML

公网烟测：/doc /chat 200；/api GET → POST only；/state 未登录 302。

3. 到口 Web / API 域名（官网与对话页）

域名	用途	公网（2026-10-20）
`https://ai.menling.com`	官网「到口数字生命」落地页	HTTP 200
`https://dk.menling.com`	到口对话 SPA（静态 + `/api/*` 反代）	HTTP 200
`https://iai.menling.com`	API 域名（同 `daokou-ai` ）	`/api/config` 200

/api/config（dk 与 iai 同源数据，已实测）关键字段：

字段	现网值（摘要）
`brand`	`到口`
`siteUrl`	`https://ai.menling.com`
`pcUrl`	`https://dk.menling.com`
`apiHost`	`https://iai.menling.com`
`voice.enabled` / `maxSeconds`	`true` / `60`
`hubs`	含 `uid:1000 name:到口 role:ai` 等
`hotTopics`	热门问题列表
`wxLoginUrl` / 下载地址	见返回 JSON

App 原生主路径仍是 §1 的 api.menling.com 私聊 1000；下列接口供 Web/嵌入或对照，不是替代 IM。

3.1 对话与会话（相对路径；Base 可用 `https://dk.menling.com` 或 `https://iai.menling.com`）

方法	路径	关键字段 / 行为	实测
GET	`/api/config`	见上	200
GET	`/api/hot-topics?limit=6`	热门问	200
POST	`/api/session/create`	body `{}` → `sessionKey`/`sessionId`/`guestId`	200
GET	`/api/session/list?guestId=`	会话列表	200（空数组）
GET	`/api/session/messages?sessionKey=`	历史消息	无效 key 现网 500（勿依赖坏参）
POST	`/api/session/delete`	`sessionKey`+`guestId`	无权时 code=0
POST	`/api/session/clear`	清空（前端有调用）	—
POST	`/api/chat`	`sessionKey`,`content`,`guestId`,`channel`,`lat`,`lng` → `data.reply`	200（有 session 可回）
POST	`/api/upload`	`multipart file` → url；仅 POST	GET → 405
POST	`/api/voice`	`multipart audio` + `sessionKey`/`guestId`/`channel` → 识别后同 chat	前端已接

鉴权（Web）：

方法	路径	说明	空参实测
POST	`/api/auth/login`	手机号/门铃号登录	提示输入手机号或门铃号
POST	`/api/auth/register`	注册	需正确手机号
POST	`/api/auth/send-code`	验证码	需正确手机号
GET	`/api/auth/me`	当前用户	未登录 code=0
POST	`/api/auth/logout`	退出	ok
POST	`/api/auth/jump`	跳转票据	需先登录
POST	`/api/auth/check-phone`	手机号校验	—
POST	`/api/auth/wx-sso`	微信 SSO	缺凭证

/api/user/passport：公网 404（前端历史路径，现网未挂；勿依赖）。

响应壳与 IM 不同：多为 { "code": 1|0, "msg": "...", "data": ... }（code=1 成功）。

4. 语音识别 / 看图 / 音视频（研究院合码重点）

4.1 语音消息 → 到口自动回（ASR）

项	说明
服务	本机 ASR `本机服务`（Docker `daokou-asr`，健康；App 勿直连内网）
App 入桥约定	私聊 1000 发文本，形如：`[语音] <公网可访问的音频 URL>`（或等价约定），服务端才会走 ASR → 同坐席意图
勿发	仅二进制语音、且不带 URL 文本 → 不进客服桥
超时参考	ASR 约 12s 量级；本机旁路健康

4.2 看图（OCR）

项	说明
IM	`contentType: 3` 图片已入桥，包成 `__dmkIMG__:` → OCR → 同坐席意图
服务	本机 OCR `:8766`（RapidOCR）；本机字节级约 0.3s 量级
App	对 1000 发图片消息（CT=3）即可；勿再调内部 OCR HTTP

4.3 语音 / 视频通话（自有 IM 信令 + WebRTC）

勿接融云 CallKit。 完整字段见：

（内部文档）
（内部文档）
（内部文档）

项	值
Base	`https://api.menling.com`
一期	两人语音 `mode=1,mediaType=1`；两人视频 `mode=2,mediaType=2`
信令	`POST /message/call/invite\|ringing\|accept\|reject\|hangup\|cancel\|sdp\|ice` 等
ICE	`GET /message/call/ice_servers`（含 TURN；以接口返回为准，勿写死账号）
事件通道（方案 A）	`GET` 或 `POST` `/message/call/pending_events`（拉取即消费；TTL 约 30s）
轮询建议	通话页 1s；App 前台来电侦听 3s
公网	`pending_events` / `ice_servers` 未登录返回 `Not loged in.`（路由通）

可对 1000 发起 invite（服务端无按号段禁止）；没有服务端「自动接听 + 通话中 ASR→答→TTS」闭环——见 §6 待合。

4.4 换头像（顺带）

https://api.menling.com：先 POST /file/upload 拿 result.url，再登录态 POST /user/set_portrait_uri body {"portraitUri":"<url>"}。现网烟测已通（见 （内部文档））。

5. 明确禁止

融云（发信 / CallKit / webhook 主路径）——一律自有 IM + WebRTC。
App 调用内部桥 /muser/menlingnew/kefuLexiconReply（仅 Node→PHP）。
把 9999 / 10000 / 1 当「到口数字生命」全能入口。
IM Base 写成 api.menkou.com。
文档/UI 使用「到口数字生命」「到口数字生命」——统一 到口数字生命。
在对接文档或客户端写死 JWT secret、ASR/OCR Token、TURN 账号。

6. 研究院还需合的缺口（待合）

通话中自动听→答→说：现网无服务端实时 ASR→LLM→TTS 管道；需 App 侧：通话中转写 → send_private 文本给 1000 → pull_private → 本地 TTS 播放（视频画面可另走看图）。
语音消息统一格式：聊天语音统一发文本 [语音] <url>（或约定等价），否则不进桥。
pending_events 轮询合入通话页：通话页 1s / 前台 3s；一期不必正式 WebSocket。
旧文档时延：若 App 文案仍写「约 1 分钟」，改为 §1.4 的 6.5–7.5s / 1–3s。
产品文案：所有入口、按钮、关于页统一「到口数字生命」，去掉「到口数字生命」字样。

7. 相关内部文档（研究院可向服务端要摘要，勿依赖路径权限）

文件	内容
`（内部文档）`	私聊 1000 自动回（时延描述已过时，以本文 §1.4 为准）
`（内部文档）`	文字回复热修与时延
`（内部文档）`	ASR/看图/通话缺口
`（内部文档）`	H5 入口修复
`（内部文档）` 等	通话 REST + pending_events

8. 验收清单（研究院）

[ ] 登录 JWT 后对 1000 send_private + pull_private 能拿到自动回（冷路径约 10s 内）。
[ ] 文案全部为「到口数字生命」。
[ ] 语音消息按 [语音] url 入桥；图片 CT=3 能回。
[ ] 语音/视频：invite + pending_events + WebRTC，无融云。
[ ] 未调用 kefuLexiconReply；未把 9999/10000 当全能。
[ ] （可选）WebView 打开 my.menkou.com/muser/aitwin/index 管理分身。

院长定：产品名 到口数字生命；合码方 中国宇宙研究院。字段以现网 api.menling.com / dk|iai.menling.com 联调为准。