常见问题¶
接入相关¶
如何开始使用 UPath？¶
- 访问 UPath 官网 注册账号
- 在官网控制台创建 API Key
- 使用 API Key 调用 AIGC 接口
详细步骤请参考 快速开始。
有示例代码吗？¶
有的，我们提供了完整的前端示例项目：
- GitHub 地址：https://github.com/c4chuan/UPath-local-demonstration
- 包含完整的接入流程和代码实现
- 可直接运行体验 AI 导师对话功能
支持哪些客户端接入？¶
UPath 提供标准的 HTTP API，支持任何能发起 HTTP 请求的客户端：
- Web 应用
- iOS / Android 应用
- 小程序
- 桌面应用
- 服务端应用
需要集成 RTC SDK 吗？¶
是的，语音对话功能需要集成 RTC SDK 来实现实时音视频通信。UPath 通过 getScenes 接口返回 RTC 连接所需的参数。
认证相关¶
JWT Token 和 API Key 有什么区别？¶
| 认证方式 | 适用场景 | 有效期 |
|---|---|---|
| JWT Token | 控制台接口 | Access Token 24 小时 |
| API Key | AIGC 接口 | 可设置永不过期 |
Token 过期后怎么办？¶
Access Token 过期后，可以使用 Refresh Token 获取新的 Access Token，无需重新登录。Refresh Token 有效期为 7 天。
可以创建多少个 API Key？¶
没有数量限制，可以根据业务需要创建多个 API Key。建议为不同的应用或环境创建独立的 Key。
API Key 泄露了怎么办？¶
立即在 官网控制台 删除该 API Key，删除后立即生效。然后创建新的 API Key 并更新到您的应用中。
如何管理 API Key？¶
所有 API Key 的创建、查看、删除操作都需要在 UPath 官网控制台 进行。
计费相关¶
如何计费？¶
AI 导师对话按对话时长计费：
- 计费单位：小时
- 费用计算：对话时长 × AI 导师场景单价
- 扣费时机：StopVoiceChat 时自动扣除
余额不足会怎样？¶
- 调用 StartVoiceChat 时会检查余额
- 余额为 0 或负数时返回
INSUFFICIENT_BALANCE错误 - 不会中断正在进行的对话
如何查看消费记录？¶
通过控制台接口 /api/transactions/ 查看所有消费记录，包括时间、金额、余额变化等详细信息。
如何充值？¶
请在 官网控制台 进行充值，或联系管理员。
技术问题¶
RoomId 有什么要求？¶
- 同一账号下 RoomId 唯一
- 建议使用有意义的字符串（如业务 ID）
- 支持字母、数字、下划线
同一个 RoomId 可以重复使用吗？¶
可以。同一 RoomId 重复调用 StartVoiceChat 会：
- 先结算上次会话费用
- 自动开始新的会话
对话会自动关闭吗？¶
系统提供多层超时保护机制：
方案一：客户端控制（推荐）
- 检测用户是否正在说话
- 用户停止说话后开始倒计时（如 30 秒）
- 倒计时结束自动调用 StopVoiceChat
- 可以避免"客户端显示连接中，但 AI 导师已退出"的情况
完整实现代码请参考 前端示例项目。
方案二：服务端状态监控（快速接入）
- StartVoiceChat 时设置
EnableStatusMonitor: true - AI 导师状态 5 分钟未更新时自动关闭
- 适合快速接入场景，减少不必要的费用损失
方案三：房间超时保护（默认）
- 对话超过 2 小时自动结束
- 作为最终的兜底措施
忘记调用 StopVoiceChat 会怎样？¶
不用担心，系统有多层保护：
- 如果启用了
EnableStatusMonitor: true，AI 导师状态 5 分钟未更新会自动关闭 - 即使未启用，对话超过 2 小时也会自动关闭
自动关闭时会正常执行计费，费用按实际对话时长计算。
推荐做法
为了最佳用户体验，建议在客户端实现语音活动检测和倒计时自动关闭。如果希望快速接入，可以启用 EnableStatusMonitor: true 将超时检测托管给服务器。
接口调用超时怎么处理？¶
建议设置合理的超时时间（如 30 秒），并实现重试机制：
- 对于幂等接口（如 getScenes），可以直接重试
- 对于非幂等接口（如 StartVoiceChat），先查询状态再决定是否重试
如何排查接口调用问题？¶
- 保存响应中的
RequestId - 通过调用日志接口查询详细记录
- 如需帮助，提供 RequestId 联系技术支持
AI 导师场景相关¶
有哪些可用的 AI 导师？¶
通过 getScenes 接口获取所有可用的 AI 导师场景列表。目前支持的 AI 导师包括：
- 英语老师
- 数学老师
- 文学老师
- 更多场景持续更新中...
不传 scene_name 参数时返回全部可用场景。
可以自定义 AI 导师吗？¶
目前暂不支持用户自定义 AI 导师场景。如有特殊需求，请联系我们。
其他问题¶
有 SDK 吗？¶
目前提供 HTTP API，暂未提供官方 SDK。您可以参考我们的 前端示例项目 进行接入。
如何获取技术支持？¶
API 有频率限制吗？¶
为保证服务稳定，API 有一定的频率限制。正常使用情况下不会触发限制。如果收到 429 错误，请降低请求频率。