API 参考

配置表、方法、事件、类型定义一览。

ChatConfig（核心配置）

参数类型必填说明
appIdstring是项目 ID
apiKeystring否API Key 或 tokenProvider 二选一
tokenProvider() => Promise<string>否临时 Token 动态获取函数，生产环境推荐，与 apiKey 二选一
baseUrlstring否API 基础地址（默认 https://pinyou.xin/api）
timeoutnumber否请求超时（默认 30000ms）
debugboolean否调试模式，打印日志
userIdstring否终端用户标识
sessionIdstring否会话标识（不传则自动生成）
ttsMode'stream' | 'websocket'否TTS 模式（默认 websocket）
ttsWebSocketTtsWebSocketConfig否TTS WebSocket 高级配置（wsUrl, forceWebSocket）

WidgetConfig（预制组件配置）

参数类型默认值说明
theme'minimal' | 'glass' | 'bubble' | 'light' | 'dark' | 'custom''minimal'主题（light/dark/custom 为旧版兼容）
draggablebooleantrue悬浮球可拖拽
defaultOpenbooleanfalse默认打开窗口
position'bottom-right' | 'bottom-left' | 'top-right' | 'top-left''bottom-right'悬浮球位置
titlestring'AI 助手'窗口标题
welcomeMessagestring-欢迎消息
widthnumber380窗口宽度
heightnumber600窗口高度
themeConfigThemeConfig-主题颜色配置
placeholderstring-输入框占位符文本
subtitlestring-窗口副标题
logoUrlstring-Logo 图片 URL
showCloseButtonbooleantrue显示关闭按钮
zIndexnumber9999窗口层级
offset{ x: number; y: number }-位置偏移量

ChatClient 方法

1// 创建客户端
2const client = new ChatClient(config);
3

4// === 消息 ===
5await client.send(content);
6await client.sendMessage({ content, conversationId, stream: true });
7await client.sendImage(file, content?);
8await client.sendVoice(file, content?);
9await client.sendVideo(file, content?);
10await client.sendWithAttachments(content, attachments);
11await client.uploadFile(file, type);
12

13// === 会话 ===
14await client.getConversations();
15await client.getConversation(id);
16await client.deleteConversation(id);
17client.newConversation();
18await client.switchConversation(id);
19client.getCurrentConversationId();
20

21// === TTS 语音播报 ===
22client.setTtsMuted(muted);
23client.playTts(messageId, text);
24client.pauseTts();
25client.resumeTts();
26client.stopTts();
27await client.generateTts(text, options?);
28client.setTtsVoice(voiceId);
29await client.getTtsVoices();
30client.setTtsAutoPlay(enabled);
31client.isTtsAutoPlay();
32client.isTtsMuted();
33client.getCurrentTtsMessageId();
34client.getTtsPlayState();
35

36// === 状态 ===
37client.getState();
38client.getMessages();
39client.setInputValue(value);
40client.getInputValue();
41client.subscribe(listener);
42

43// === 控制 ===
44client.abortMessage(messageId);
45client.abortAll();
46client.destroy();
47

48// === 事件 ===
49client.on(event, handler);
50client.once(event, handler);
51client.off(event, handler);

事件类型

事件说明
connected连接建立
disconnected断开连接
message:sending消息发送中
message:sent消息已发送
message:received收到回复
message:stream:start流式响应开始
message:stream:chunk流式数据块
message:stream:delta流式增量文本
message:stream:end流式响应结束
message:stream:usageToken 用量统计（promptTokens, completionTokens, totalTokens）
message:stream:aborted流式传输被中止
message:error消息错误
conversation:created会话创建
conversation:updated会话更新
tts:startTTS 开始播放
tts:playTTS 音频片段播放
tts:endTTS 播放结束
tts:errorTTS 错误
tts:pauseTTS 暂停
tts:stopTTS 停止
tts:audioTTS 音频数据
error全局错误

类型定义

1interface Message {
2  id: string;
3  conversationId: string;
4  role: 'user' | 'assistant' | 'system';
5  content: string;
6  status: 'pending' | 'sending' | 'streaming' | 'success' | 'error' | 'aborted';
7  createdAt: Date;
8  attachments?: MediaAttachment[];
9  metadata?: Record<string, unknown>;
10}
11

12type MediaType = 'image' | 'audio' | 'video' | 'file';
13

14interface MediaAttachment {
15  type: MediaType;
16  url: string;
17  mimeType?: string;
18  name?: string;
19  size?: number;
20  duration?: number;     // 秒，音视频
21}
22

23interface UploadResult {
24  url: string;
25  objectName: string;
26  mimeType: string;
27  size: number;
28  name?: string;
29}
30

31interface TtsOptions {
32  voice?: string;        // 音色 ID
33  projectId?: string;    // 项目 ID
34  conversationId?: string; // 对话 ID
35  mode?: 'api' | 'websocket'; // 播放模式
36}
37

38interface TtsResult {
39  audioUrl: string;
40  characters: number;
41  model: string;
42  voice: string;
43}

媒体上传 API

方法参数说明
uploadFile(file, type)File/Blob, 'image'|'audio'|'video'|'file'上传文件，返回 UploadResult
sendImage(file, content?)File/Blob, string?上传并发送图片消息
sendVoice(file, content?)File/Blob, string?上传并发送语音消息
sendVideo(file, content?)File/Blob, string?上传并发送视频消息
sendWithAttachments(content, attachments)string, MediaAttachment[]发送带附件的消息

文件限制

图片

最大 10MB

jpeg, png, gif, webp, bmp

音频

最大 25MB

mp3, wav, ogg, aac, webm, flac, amr, opus, silk

视频

最大 50MB

mp4, webm, quicktime

文件

最大 30MB

pdf, doc/docx, xls/xlsx, ppt/pptx, txt, csv, md, json, zip