领内AI伴侣云 · API 文档

← 返回首页

概览

领内AI伴侣云提供标准 RESTful API，支持企业客户快速接入 AI 角色对话、记忆管理、计费与白标等能力。本文档覆盖已上线接口（v1）及规划中接口（v2 草案）。

💡 所有已上线接口均可通过控制台 API Key 直接调用，无需额外申请。

Base URL

https://www.lingnei.cn

完整示例：

https://www.lingnei.cn/chat/completions

鉴权方式

类型Header用途
Bearer JWTAuthorization: Bearer <JWT>企业管理端接口（登录后获得，2h 有效）
API KeyX-App-Key: pk_live_...业务/角色对话/记忆接口（第三方应用调用）

统一响应格式

{
  "code": 0,
  "message": "success",
  "data": {},
  "request_id": "..."
}

code=0 成功；非 0 为业务错误。SSE 流式接口（stream=true）逐条返回 data: {...}\n\n。

错误码

code含义
0成功
40000参数错误
40100未授权 / 无效 Key
40300禁止（权限不足 / 企业未审核）
40400 / 40401资源不存在 / 接口不存在
40900冲突（重复注册等）
50000服务器内部错误

2.1 认证

公开 除 logout 外无需鉴权。

方法路径说明
POST/auth/sms/send发送短信验证码 {phone, purpose(register/login)}
POST/auth/register企业注册（审核即批 active）
POST/auth/login登录，返回 {token, enterprise}
POST/auth/logout登出 Bearer

2.2 API Key 管理

Bearer

方法路径说明
GET/api-keys列表（脱敏）
POST/api-keys创建 {name, allowed_characters[]}，仅此一次返回明文 key
DELETE/api-keys/{id}吊销

2.3 角色

方法路径鉴权说明
GET/charactersX-App-Key角色列表（平台全量）
POST/characters/{id}/openBearer开通角色（付费）

2.4 对话 / 记忆

X-App-Key

POST /chat/completions — 对话

支持流式 SSE（stream=true）和语音友好模式（voice_mode=true）。

请求参数

字段类型必填说明
character_idstring✅角色 ID
messagestring✅用户消息
user_idstring—终端用户标识，默认 anonymous
historyarray—历史对话 [{role, content}]
streambool—是否 SSE 流式输出
voice_modebool—语音友好模式：输出简短、无动作描述，适合 TTS 播报

示例

curl -X POST https://www.lingnei.cn/chat/completions \
  -H "X-App-Key: pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"character_id":"lin_daiyu","message":"你好","stream":false,"voice_mode":true}'

POST /demo/chat — 游客演示

免鉴权免计费。入参 {character_id, message, voice_mode?}

记忆接口

方法路径说明
GET/memory/{u}/{c}读记忆 ?memory_type=all
POST/memory/{u}/{c}更新记忆 {memories:[...]}
POST/memory/{u}/{c}/search语义搜索 {query, top_k?}

2.5 账户 / 计费 / 钱包

Bearer

方法路径说明
GET/account账户信息（余额、已开通角色、token 单价）
POST/account/profile更新资料
POST/account/password修改密码
GET/billing/quota配额（本月已用 / 总量 / 重置时间）
GET/billing/usage用量 ?group_by=day|character|hour&start_date&end_date
GET/billing/statements账单明细 ?page&size&type&start&end
POST/wallet/recharge充值下单 {amount(元), subject?}
GET/wallet/orders订单列表 ?page
POST/wallet/orders/{no}/mark-paid模拟到账（沙箱）

2.6 管理员

Bearer + is_admin=true

方法路径说明
GET/admin/pricing定价总览
POST/admin/pricing/token更新 token 单价
POST/admin/characters/{id}/price更新角色定价
GET/admin/orders全部订单
GET/admin/enterprises企业列表
POST/admin/enterprises/{id}/review企业审核
GET/admin/characters角色管理
PATCHPOST/admin/characters/{id}更新角色（含 visibility）
GET/admin/revenue收入统计
GET / POST/admin/model模型配置

2.7 支付宝支付回调

方法路径说明
GET/pay/alipay/return同步回跳页
POST/pay/alipay/notify异步回调，响应纯文本 success

3.1 API Key 权限增强（v2 草案）

api_key 表新增 scopes JSONB（默认 ["chat:read","chat:write"]）。

方法路径说明
PATCH/api-keys/{id}更新 {name?, scopes[]?, allowed_characters[]?}

scopes 枚举：chat:read、chat:write、memory:read、memory:write、billing:read、admin

3.2 Webhook（v2 草案）

Bearer

方法路径说明
GET/webhooks列表
POST/webhooks注册 {url, events[], name?, secret?}
PATCH/webhooks/{id}更新
DELETE/webhooks/{id}删除
POST/webhooks/{id}/test发送测试事件

事件类型：conversation.started、conversation.finished、conversation.error、quota.threshold、key.revoked、payment.succeeded

回调签名：X-Cbrain-Signature = sha256_hmac(payload, secret)

3.3 角色配置（v2 草案）

Bearer — 企业×角色级自定义配置

方法路径说明
GET/characters/{id}/config获取配置
PUT/characters/{id}/config更新 {style, memory_depth, max_tokens, temperature, top_p, welcome_greeting}

3.4 用量仪表盘（v2 草案）

Bearer

方法路径说明
GET/analytics/overview总览：累计调用/token/费用、本月调用、热门角色 Top5
GET/analytics/usage明细 ?period=YYYY-MM&character_id&app_id
GET/analytics/latency延迟统计 ?period&character_id

3.5 Widget 配置（v2 草案）

方法路径鉴权说明
GET/widget/configBearer 或 Key获取 Widget 配置 JSON
PUT/widget/configBearer更新 {position, theme_color, welcome_message, logo_url, brand_name, font}

3.6 白标 / 子账号（v2 草案）

应用管理 Bearer

方法路径说明
GET/apps应用列表
POST/apps创建 {name, description?}
PATCH/apps/{id}更新
DELETE/apps/{id}删除
GET/apps/{id}/keys该应用下 Key 列表

成员管理 Bearer

方法路径说明
GET/members成员列表
POST/members邀请 {phone, name?, role}
PATCH/members/{id}更新 {role?, permission[]?}
DELETE/members/{id}移除

角色：owner / admin / developer / viewer

白标配置 Bearer

方法路径说明
GET/branding白标配置
PUT/branding更新 {custom_domain, brand_name, logo_url, favicon_url, footer_text}

3.7 内容合规（v2 草案）

方法路径鉴权说明
GET/complianceBearer合规配置
PUT/complianceBearer更新 {blocked_words[], banned_topics[], enable_moderation}
POST/compliance/checkKey检测 {text} → {hit, matched[]}

3.8 硬件设备接入（v2 规划 · Coming Soon）

⚠️ 以下为规划占位，尚未实现。面向 AI 硬件 / 玩具接入场景。
方法路径说明
POST/devices设备注册 {device_id, product_type, name?}
GET/devices设备列表
DELETE/devices/{id}注销设备
GET/devices/{id}/wake-words读取唤醒词
POST/devices/{id}/wake-words配置唤醒词 {wake_words[], character_id?}
POST/devices/{id}/voice语音交互（流式 SSE）

SDK 接入建议

  1. 认证封装：SDK 内部封装「企业登录换 JWT」与「X-App-Key 业务调用」两套 client
  2. 对话流式：stream=true 按 SSE 逐行解析 data: 事件，支持断线重连
  3. 记忆读写：提供 remember() / recall() / search() 糖方法
  4. Webhook：提供 HMAC-SHA256 签名校验工具
  5. Widget：JS 片段 + GET /widget/config 拉配置渲染聊天窗口
  6. 错误处理：统一解析 code，429/50000 建议指数退避重试
📧 接入咨询：请联系 深圳市领内网络科技有限公司
文档最后更新：2026-09-21