接入指南

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

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返回给前端：

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

5export default async function handler(req, res) {
6  // 从你的数据库或会话中获取当前用户ID
7  const userId = req.session.userId;
8

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

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

前端调用示例：

// 前端从你的后端获取临时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写死在环境变量或配置文件中！

重要：请妥善保管 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 / 小程序」章节，有完整的框架级接入方案。