后端对接

通过 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是终端用户唯一标识（你系统中的用户 ID）
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 小时，过期后需重新交换。

非流式对话

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  }'

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

对话消息支持携带多模态附件。平台会将附件 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};