文档/后端对接

后端对接

对接平台 API、临时 Token、SSE 和多模态接口。

后端对接

通过 HTTP API 直接对接，适用于任何后端语言。以下示例覆盖 cURL、Python、Java、Go。

概述

平台提供标准 RESTful API，所有接口均以 /api/v1/chat 为前缀。 支持非流式和流式（SSE）两种对话模式，以及 TTS 语音合成、ASR 语音识别、媒体文件上传等能力。

Base URL：https://pinyou.xin/api

认证方式

⭐ 前端请使用临时Token！

前端SDK和WebSocket请使用临时Token（tmp_live_xxx），不是API Key！ 临时Token有效期1小时，即使泄露也更安全。

后端API调用（如交换临时Token）使用：

后端认证头格式（仅用于后端交换临时Token）bash
1X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的API Key（仅在后端使用！）
2X-App-Id: your-project-id

前端SDK调用（Web/小程序）使用：

前端认证头格式（使用临时Token）bash
1X-API-Key: tmp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # ⭐ 临时Token
2X-App-Id: your-project-id

重要： API Key 永远不要暴露在前端代码中！只应该在后端服务器上使用API Key来交换临时Token，然后将临时Token返回给前端使用。

临时 Token 交换

POST/api/v1/auth/exchange-token

用 API Key 换取有效期 1 小时的临时 Token，供前端 SDK 安全使用。此接口仅在后端服务器调用。

请求头

Header必填说明
X-API-Key是API Key（sk_live_xxx 格式）
X-App-Id是项目 ID（UUID 格式）
Content-Type是application/json

请求体

参数类型必填说明
endUserIdstring是终端用户唯一标识。必须由后端从登录态解析，禁止使用前端传入值。
metadataRecord<string, any>否自定义元数据，如用户名、角色等业务信息

响应体

成功响应示例json
1{
2  "code": 200,
3  "message": "success",
4  "data": {
5    "tempToken": "tmp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
6    "expiresIn": 3600,
7    "expiresAt": "2026-03-18T10:00:00Z"
8  }
9}

安全提示：此接口必须在后端服务器调用，切勿在前端暴露 API Key。返回的 tempToken 有效期 1 小时，过期后需重新交换。

错误示例（禁止）

// ❌ 不要这样做：直接信任前端传来的 userId
app.post('/api/auth/temp-token', async (req, res) => {
  const userId = req.body.userId;
  // ... 用 userId 交换 temp token
});

用户鉴权红线（项目 / 机器人）

外部接口（Dynamic HTTP / MCP）建议按能力声明鉴权模式。不要把所有接口都当成同一种认证方式。

模式适用场景项目可用机器人可用
NONE公开接口或租户级固定凭证是是
END_USER_ID按当前登录用户鉴权（后端解析用户ID）是否（无用户上下文）
FORWARD_USER_TOKEN透传外部系统用户token（头名/前缀可配置）是否（无用户上下文）

安装约束：凡是声明为 END_USER_ID 或 FORWARD_USER_TOKEN 的接口， 只能安装到「项目」，不能安装到「机器人」。

非流式对话

POST/api/v1/chat/completions

请求体参数：

参数类型必填说明
projectIdstring是项目 ID
messagesarray是消息列表，每条包含 role（user/assistant/system）、content 和可选 attachments
conversationIdstring否会话 ID，用于多轮对话
endUserIdstring否终端用户标识
sessionIdstring否会话标识，用于区分同一用户的不同会话
streamboolean否是否流式返回（默认 false）
modestring否对话模式：auto（自动判断 RAG）、rag（强制 RAG）、chat（纯对话），默认 auto
temperaturenumber否温度参数 0~2，越高越随机（默认 0.7）
maxTokensnumber否最大输出 Token 数（默认 2000）
dataSourceIdsstring[]否指定 RAG 数据源 ID 列表
metadataobject否自定义元数据，透传到对话上下文
cURL - 非流式对话（后端使用API Key）bash
1# ⭐ 注意：这是后端服务器调用示例，使用API Key（sk_live_xxx）
2# 前端应该使用临时Token（tmp_live_xxx）
3

4curl -X POST https://pinyou.xin/api/v1/chat/completions \
5  -H "Content-Type: application/json" \
6  -H "X-API-Key: sk_live_YOUR_API_KEY" \
7  -H "X-App-Id: YOUR_PROJECT_ID" \
8  -d '{
9    "projectId": "YOUR_PROJECT_ID",
10    "messages": [
11      {"role": "user", "content": "你好，请介绍一下你自己"}
12    ]
13  }'

响应示例：

成功响应json
1{
2  "code": 200,
3  "message": "success",
4  "data": {
5    "content": "你好！我是 AI 助手...",
6    "conversationId": "conv_abc123",
7    "usage": {
8      "inputTokens": 12,
9      "outputTokens": 56
10    }
11  }
12}

流式对话 (SSE)

POST/api/v1/chat/stream

请求参数与非流式一致。响应为 Server-Sent Events（SSE）流，逐字返回 AI 回复内容。

cURL - 流式对话（后端使用API Key）bash
1# ⭐ 注意：这是后端服务器调用示例，使用API Key（sk_live_xxx）
2curl -N -X POST https://pinyou.xin/api/v1/chat/stream \
3  -H "Content-Type: application/json" \
4  -H "X-API-Key: sk_live_YOUR_API_KEY" \
5  -H "X-App-Id: YOUR_PROJECT_ID" \
6  -H "Accept: text/event-stream" \
7  -d '{
8    "projectId": "YOUR_PROJECT_ID",
9    "messages": [
10      {"role": "user", "content": "用 Python 写一个快速排序"}
11    ]
12  }'

SSE 响应格式

流式响应每行一个 data: 事件，以空行结束。以 data: [DONE] 表示结束。

SSE 响应示例bash
1data: {"type":"init","conversationId":"conv_abc123"}
2

3data: {"type":"message","delta":"你好"}
4

5data: {"type":"message","delta":"，"}
6

7data: {"type":"message","delta":"我是"}
8

9data: {"type":"message","delta":" AI "}
10

11data: {"type":"done","usage":{"promptTokens":10,"completionTokens":25,"totalTokens":35}}
12

13data: [DONE]
type字段说明
initconversationId会话 ID，用于多轮对话
messagedelta增量文本片段，累加得到完整回复
analyzing—多模态内容（图片/音频/视频）分析中
doneusage最终用量统计（promptTokens / completionTokens / totalTokens）
errormessage错误信息，收到后流式结束

请求频率超限（429）处理建议

收到 429 错误时，建议采用指数退避（Exponential Backoff）策略重试：

Python 指数退避重试示例python
1import time
2import requests
3

4def chat_with_retry(messages, max_retries=5):
5    for attempt in range(max_retries):
6        try:
7            response = requests.post(
8                "https://pinyou.xin/api/v1/chat/stream",
9                headers={
10                    "Content-Type": "application/json",
11                    "X-API-Key": os.getenv("LINGSHUAI_API_KEY"),
12                    "X-App-Id": os.getenv("LINGSHUAI_APP_ID"),
13                    "Accept": "text/event-stream",
14                },
15                json={"projectId": APP_ID, "messages": messages},
16                stream=True,
17            )
18

19            if response.status_code == 200:
20                return response
21            elif response.status_code == 429:
22                # 指数退避：1s → 2s → 4s → 8s → 16s
23                wait_time = 2 ** attempt
24                print(f"请求超限，{wait_time}秒后重试（第{attempt + 1}次）...")
25                time.sleep(wait_time)
26            else:
27                raise Exception(f"请求失败: {response.status_code}")
28

29        except requests.exceptions.RequestException as e:
30            if attempt == max_retries - 1:
31                raise
32            time.sleep(2 ** attempt)
33

34    raise Exception("达到最大重试次数")
共 34 行

多模态附件（图片 / 音频 / 视频）

对话消息支持携带多模态附件。平台会将附件 URL 传递给 AI 模型进行分析，文件本身由客户自行存储和管理。

推荐方式：传入自托管文件 URL

将文件存储在您自己的 OSS / CDN（如阿里云 OSS、腾讯云 COS、AWS S3 等），在对话请求的 attachments 中传入公开可访问的 URL。 文件生命周期完全由您控制，聊天记录中的附件可永久预览。

cURL - 直接传入外部 URL（推荐，后端使用API Key）bash
1# ⭐ 注意：这是后端服务器调用示例，使用API Key（sk_live_xxx）
2curl -X POST https://pinyou.xin/api/v1/chat/stream \
3  -H "Content-Type: application/json" \
4  -H "X-API-Key: sk_live_YOUR_API_KEY" \
5  -H "X-App-Id: YOUR_PROJECT_ID" \
6  -d '{
7    "projectId": "YOUR_PROJECT_ID",
8    "stream": true,
9    "messages": [{
10      "role": "user",
11      "content": "请描述这张图片",
12      "attachments": [{
13        "type": "image",
14        "url": "https://your-oss.com/images/photo.jpg",
15        "mimeType": "image/jpeg"
16      }]
17    }]
18  }'

attachments 字段说明

字段类型必填说明
typestring是附件类型：image / audio / video
urlstring是文件公开访问 URL（自托管或平台上传返回的 URL）
mimeTypestring否MIME 类型（如 image/jpeg），不传则自动推断
namestring否文件名

便捷方式：使用平台上传接口

适合快速测试或小程序等不方便自建存储的场景。通过 POST /api/v1/chat/media/upload 上传文件，获取临时 URL。

注意：平台上传的文件为临时存储，AI 处理完成后即删除。不可用于聊天记录的持久化预览。 如需持久化附件，请使用上方推荐的自托管方式。

参数类型说明
fileFile上传的文件（multipart/form-data）
typestring文件类型：image / audio / video / file（默认 image）
cURL - 上传图片（临时存储，后端使用API Key）bash
1# ⭐ 注意：这是后端服务器调用示例，使用API Key（sk_live_xxx）
2curl -X POST https://pinyou.xin/api/v1/chat/media/upload \
3  -H "X-API-Key: sk_live_YOUR_API_KEY" \
4  -H "X-App-Id: YOUR_PROJECT_ID" \
5  -F "file=@/path/to/image.png" \
6  -F "type=image"

文件大小限制：图片 10MB、音频 25MB、视频 50MB、文件（PDF/Office 等）30MB。每日上传配额 500MB。

TTS 语音合成

POST/api/v1/chat/tts
参数类型必填说明
textstring是要合成的文本
projectIdstring是项目 ID
voicestring否音色名称，可通过 /tts/voices 获取
cURL - TTS 语音合成（后端使用API Key）bash
1# ⭐ 注意：这是后端服务器调用示例，使用API Key（sk_live_xxx）
2curl -X POST https://pinyou.xin/api/v1/chat/tts \
3  -H "Content-Type: application/json" \
4  -H "X-API-Key: sk_live_YOUR_API_KEY" \
5  -H "X-App-Id: YOUR_PROJECT_ID" \
6  -d '{"text": "你好世界", "projectId": "YOUR_PROJECT_ID"}'

获取可用音色列表：GET /api/v1/chat/tts/voices

可用音色（CosyVoice v3）

音色 ID名称描述
longxiaochun_v3龙小淳女声 · 温柔（默认）
longyuan_v3龙媛女声 · 知性
longhua_v3龙华男声 · 沉稳
longanyang龙安洋男声 · 阳光
longanhuan龙安欢女声 · 元气
longjielidou_v3龙杰力豆男声 · 活力
longshu_v3龙书男声 · 播音
longshuo_v3龙硕男声 · 自然
longmiao_v3龙妙女声 · 甜美
longxiaoxia_v3龙小夏女声 · 活泼
longwan_v3龙婉女声 · 温婉
longfei_v3龙飞男声 · 磁性

ASR 语音识别

POST/api/v1/chat/asr/recognize
参数类型说明
fileFile音频文件（multipart/form-data）
projectIdstring项目 ID
cURL - ASR 语音识别（后端使用API Key）bash
1# ⭐ 注意：这是后端服务器调用示例，使用API Key（sk_live_xxx）
2curl -X POST https://pinyou.xin/api/v1/chat/asr/recognize \
3  -H "X-API-Key: sk_live_YOUR_API_KEY" \
4  -H "X-App-Id: YOUR_PROJECT_ID" \
5  -F "file=@/path/to/audio.mp3" \
6  -F "projectId=YOUR_PROJECT_ID"

错误码

HTTP 状态码code说明
200200请求成功
400400请求参数错误
401401⭐ 未授权（临时Token无效或过期，请重新从后端获取）
402402余额不足
403403无权访问该项目
429429请求频率超限
500500服务器内部错误
错误响应示例json
1{
2  "code": 401,
3  "message": "⭐ 临时Token无效或已过期，请从后端重新获取（tmp_live_xxx格式）",
4  "data": null
5}

WebSocket 端点

平台提供 3 个 WebSocket 端点，用于实时语音交互。连接时通过 Query 参数传递认证信息。

端点用途认证参数
/api/ws/tts双向流式 TTS 语音合成token=tmp_xxx 或 apiKey=sk_xxx
/api/ws/asr实时 ASR 语音识别token=tmp_xxx&projectId=xxx&format=pcm&sampleRate=16000
/api/ws/rtc实时语音对话（ASR + AI + TTS + 打断）token=tmp_xxx

TTS WebSocket 协议

客户端 → 服务端

start — 开始合成会话

text — 发送待合成文本

flush — 请求立即输出音频

stop — 停止当前合成

end — 结束会话

服务端 → 客户端

ready — 连接就绪

audio — 音频数据块（base64）

complete — 合成完成，含 characters 字段

error — 错误信息

ASR WebSocket 协议

客户端 → 服务端

二进制帧 — PCM/AAC 音频数据

{"action":"stop"} — 停止录音，等待最终结果

{"action":"cancel"} — 取消会话

服务端 → 客户端

ready — 连接就绪

partial — 临时识别结果（实时更新）

final — 一句话最终结果

complete — 所有识别完成

error — 错误信息

RTC 实时对话协议

客户端 → 服务端

start — 开始对话

audio — 音频数据帧（二进制）

interrupt — 打断 AI 说话

end — 结束对话

服务端 → 客户端

ready — 连接就绪

transcription — 用户语音转文字

text — AI 文本回复

audio — AI 语音回复（base64）

interrupted — 已响应打断

complete — 对话回合结束

error — 错误信息

WebSocket 连接示例javascript
1// TTS WebSocket 连接
2const ws = new WebSocket('wss://pinyou.xin/api/ws/tts?token=tmp_live_xxx');
3

4ws.onopen = () => {
5  ws.send(JSON.stringify({ type: 'start', voice: 'longxiaochun_v3', projectId: 'your-project-id' }));
6  ws.send(JSON.stringify({ type: 'text', content: '你好，欢迎使用灵数AI平台' }));
7  ws.send(JSON.stringify({ type: 'flush' }));
8};
9

10ws.onmessage = (event) => {
11  const msg = JSON.parse(event.data);
12  if (msg.type === 'audio') {
13    // msg.data 为 base64 编码的音频数据
14    playAudio(msg.data);
15  }
16};