文档/接入指南

接入指南

5 分钟完成最小可用接入，先跑通再扩展。

接入指南

获取凭证，一个 script 标签即可接入 AI 对话。

整体接入流程

① 注册账号→② 创建项目，获取 API Key→③ 后端交换临时 Token→④ 前端初始化 SDK→⑤ 接入完成！

前置要求

  • • 织元枢AI 平台账号
  • • 一个后端服务（任意语言）
  • • 前端页面（任意框架或纯 HTML）

关键原则

  • • API Key（sk_live_xxx）仅存后端！
  • • 前端永远使用临时 Token
  • • 临时 Token 有效期 1 小时
  • • endUserId / 外部用户Token 只在后端从登录态解析

接入时长

  • • 最低代码量：1 个 script 标签
  • • React/Vue/UniApp：约 20 行代码
  • • 预计接入时间：3 分钟
1

获取临时 Token（推荐）或 API Key

创建 API Key（仅后端使用）

控制台 → API Keys → 创建

格式：sk_live_xxxxxxxx

⭐ API Key 仅用于后端交换临时Token，前端请使用 tmp_live_xxx 格式的临时Token

获取项目 ID (appId)

控制台 → 项目 → 点进详情页复制

格式：UUID，如 a1b2c3d4-...

⭐ 推荐：使用临时 Token（临时Token）

强烈建议在前端使用临时Token而不是直接使用API Key！ 临时Token有效期1小时，即使泄露也不会造成严重影响。

临时Token格式：tmp_live_xxxxxxxx

⭐ 如何动态获取临时Token？

在您的后端服务器上使用API Key调用交换接口，动态生成临时Token返回给前端：

强约束：endUserId 必须在后端从登录态解析， 不能从前端参数透传（例如 req.body.userId）。

Node.js - 后端动态交换临时Tokenjavascript
1// ⭐ 后端接口示例：动态交换临时Token
2// 文件：/api/auth/temp-token.js
3import axios from 'axios';
4

5export default async function handler(req, res) {
6  // ✅ 正确做法：从后端登录态(JWT/Session)解析用户ID
7  // ❌ 禁止：const userId = req.body.userId
8  const userId = req.session?.userId; // 或 req.auth.sub
9  if (!userId) return res.status(401).json({ error: 'unauthorized' });
10

11  try {
12    // 调用灵数AI平台交换临时Token
13    const response = await axios.post(
14      'https://pinyou.xin/api/v1/auth/exchange-token',
15      {
16        endUserId: userId,  // 来自后端登录态解析
17        metadata: { username: req.session.username }  // 可选元数据
18      },
19      {
20        headers: {
21          'Content-Type': 'application/json',
22          'X-API-Key': process.env.LINGSHUAI_API_KEY,  // ⭐ API Key存在后端环境变量
23          'X-App-Id': process.env.LINGSHUAI_APP_ID
24        }
25      }
26    );
27

28    // 返回临时Token给前端
29    res.json({
30      tempToken: response.data.data.tempToken,
31      expiresIn: response.data.data.expiresIn
32    });
33  } catch (error) {
34    res.status(500).json({ error: 'Failed to exchange token' });
35  }
36}
共 36 行

前端调用示例：

// 前端从你的后端获取临时Token
const response = await fetch('/api/auth/temp-token', {
  method: 'POST',
  credentials: 'include'  // 携带session cookie
});
const { tempToken } = await response.json();

// 使用临时Token初始化SDK
LingShuAIChat.init({
  apiKey: tempToken,  // ⭐ 使用动态获取的临时Token
  appId: 'your-project-id'
});

⭐ 前端每次需要Token时，都应该调用你的后端接口来动态获取，不要把Token写死在环境变量或配置文件中！

鉴权红线（必须遵守）

  • 1. 如果你的业务有登录态，endUserId 必须在后端从登录态 token 解析，不能信任前端传参。
  • 2. 如果外部系统要求用户级 token（如 CRM / 物流 / 能源系统），也必须由后端代管并透传，前端不保存长期凭证。
  • 3. 无登录态项目可使用匿名模式，不传 endUserId；此时仅能访问租户级能力，不做用户级权限控制。

跨会话用户画像（长期记忆）生效条件

  • 1. 只要同一用户持续使用稳定且唯一的 endUserId，即使创建新会话，也能继承该用户画像与长期记忆。
  • 2. 新会话不展示旧消息是正常产品行为，但 AI 仍可基于历史画像进行个性化回答。
  • 3. 若每次都使用随机 ID 或丢失 endUserId，记忆会被拆散，无法形成跨会话连续体验。

重要：请妥善保管 API Key，永远不要暴露在前端代码中或提交到代码仓库。建议通过环境变量管理，仅用于后端交换临时Token。

2

最快接入

一个 script 标签，任何网站都能用

在 HTML 中添加以下代码html
1<!-- 引入 SDK -->
2<script src="https://unpkg.com/@lingshuai/chat-widget"></script>
3

4<!-- 初始化 -->
5<script>
6  // ⭐ 第一步：从你的后端动态获取临时Token
7  async function initChat() {
8    const response = await fetch('/api/auth/temp-token', {
9      method: 'POST',
10      credentials: 'include'  // 携带session cookie
11    });
12    const { tempToken } = await response.json();
13

14    // ⭐ 第二步：使用临时Token初始化SDK
15    LingShuAIChat.init({
16      apiKey: tempToken,  // ⭐ 使用动态获取的临时Token（tmp_live_xxx格式）
17      appId: 'your-project-id',  // 替换为你的项目 ID
18      title: '智能客服',
19      welcomeMessage: '您好！有什么可以帮助您的？',
20    });
21  }
22

23  // 页面加载后初始化
24  initChat();
25</script>

⚠️ 注意：不要直接在前端代码中写死 API Key（sk_live_xxx）！必须通过后端接口动态获取临时Token（tmp_live_xxx）。

3

验证清单

  • 页面右下角出现聊天悬浮球
  • 发送消息后能收到 AI 回复
  • 流式响应实时显示（打字效果）
  • 刷新页面后会话记录保持

常见问题

Q: 提示 401 Unauthorized？

⭐ 检查是否使用了临时Token（tmp_live_xxx格式），而不是直接使用API Key（sk_live_xxx格式）。临时Token有效期1小时，过期后需重新交换。

Q: 想用 React / Vue / UniApp？

请查看左侧「框架集成」或「UniApp / 小程序」章节，有完整的框架级接入方案。