AIGC 接口¶
AIGC 接口是 UPath AI 导师平台的核心接口，用于获取 AI 导师配置和进行语音对话。
认证方式
所有 AIGC 接口需要使用 API Key 认证，请在请求头中添加 X-API-Key。
示例项目
查看 前端示例项目 了解完整的接入代码。
接口列表¶
| 接口 | 说明 |
|---|---|
| getScenes | 获取 AI 导师场景配置和 RTC 连接信息 |
| StartVoiceChat | 开启与 AI 导师的语音对话 |
| StopVoiceChat | 结束与 AI 导师的语音对话 |
| getBalance | 查询账户余额与消费统计 |
getScenes - 获取 AI 导师配置¶
获取可用的 AI 导师场景列表及配置信息，返回 RTC SDK 连接所需的参数。
请求¶
地址：POST https://api.upath.cn/api/aigc/getScenes
请求头：
| 参数 | 必填 | 说明 |
|---|---|---|
| X-API-Key | 是 | API 密钥 |
| Content-Type | 是 | application/json |
请求参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| scene_name | string | 否 | AI 导师场景名称，不传返回所有场景 |
| RoomId | string | 是 | 房间 ID，自定义字符串 |
| UserId | string | 否 | 用户 ID |
| TaskId | string | 否 | 任务 ID |
响应¶
成功响应：
| 字段 | 类型 | 说明 |
|---|---|---|
| ResponseMetadata.Action | string | getScenes |
| Result.scenes | array | AI 导师场景列表 |
| Result.scenes[].SceneID | string | 场景 ID |
| Result.scenes[].SceneName | string | AI 导师名称（如：英语老师、数学老师） |
| Result.scenes[].rtc | object | RTC 连接配置 |
| Result.scenes[].rtc.AppId | string | RTC 应用 ID |
| Result.scenes[].rtc.RoomId | string | 房间 ID |
| Result.scenes[].rtc.UserId | string | 用户 ID |
| Result.scenes[].rtc.Token | string | RTC Token |
RTC 连接
使用响应中的 rtc 字段配置 RTC SDK，加入房间后即可开始与 AI 导师语音对话。
错误码¶
| 错误码 | HTTP 状态码 | 说明 |
|---|---|---|
| InvalidParameter | 400 | RoomId 参数不能为空 |
| SceneNotFound | 404 | 指定的 AI 导师场景不存在 |
StartVoiceChat - 开启 AI 导师对话¶
开启与 AI 导师的语音对话服务。调用前会自动检查账户余额。
请求¶
地址：POST https://api.upath.cn/api/aigc/proxy?Action=StartVoiceChat
请求头：
| 参数 | 必填 | 说明 |
|---|---|---|
| X-API-Key | 是 | API 密钥 |
| Content-Type | 是 | application/json |
请求参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| SceneID | string | 是 | AI 导师场景 ID |
| inputParams | object | 是 | 输入参数 |
| inputParams.RoomId | string | 是 | 房间 ID |
| inputParams.UserId | string | 否 | 用户 ID |
| inputParams.TaskId | string | 否 | 任务 ID |
| EnableStatusMonitor | boolean | 否 | 是否启用状态监控，默认 false |
响应¶
成功响应：
| 字段 | 类型 | 说明 |
|---|---|---|
| ResponseMetadata.Action | string | StartVoiceChat |
| ResponseMetadata.RequestId | string | 请求 ID |
| Result | object | 服务返回结果 |
错误码¶
| 错误码 | HTTP 状态码 | 说明 |
|---|---|---|
| InvalidParameter | 400 | RoomId 参数不能为空 |
| INSUFFICIENT_BALANCE | 403 | 账户余额不足 |
| PRICING_CONFIG_NOT_FOUND | 404 | AI 导师场景计费配置不存在 |
余额检查
调用此接口前会自动检查账户余额，余额为 0 或负数时将返回 INSUFFICIENT_BALANCE 错误。请在 官网控制台 及时充值。
StopVoiceChat - 结束 AI 导师对话¶
结束与 AI 导师的语音对话服务，并返回本次对话的计费信息。
请求¶
地址：POST https://api.upath.cn/api/aigc/proxy?Action=StopVoiceChat
请求头：
| 参数 | 必填 | 说明 |
|---|---|---|
| X-API-Key | 是 | API 密钥 |
| Content-Type | 是 | application/json |
请求参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| SceneID | string | 是 | AI 导师场景 ID |
| inputParams | object | 是 | 输入参数 |
| inputParams.RoomId | string | 是 | 房间 ID |
响应¶
成功响应：
| 字段 | 类型 | 说明 |
|---|---|---|
| ResponseMetadata.Action | string | StopVoiceChat |
| ResponseMetadata.RequestId | string | 请求 ID |
| Result | object | 服务返回结果 |
| BillingInfo | object | 计费信息 |
BillingInfo 字段说明：
| 字段 | 类型 | 说明 |
|---|---|---|
| duration_seconds | integer | 对话时长（秒） |
| duration_hours | float | 对话时长（小时） |
| price_per_hour | float | 单价（元/小时） |
| total_charge | float | 本次费用（元） |
| balance_before | float | 扣费前余额 |
| balance_after | float | 扣费后余额 |
错误码¶
| 错误码 | HTTP 状态码 | 说明 |
|---|---|---|
| InvalidParameter | 400 | RoomId 参数不能为空 |
| RoomNotFound | 404 | 房间不存在或已结束 |
getBalance - 查询账户余额¶
查询当前 API Key 所属账户的余额和消费统计信息。
请求¶
地址：GET https://api.upath.cn/api/aigc/balance
请求头：
| 参数 | 必填 | 说明 |
|---|---|---|
| X-API-Key | 是 | API 密钥 |
请求参数：无
响应¶
成功响应：
| 字段 | 类型 | 说明 |
|---|---|---|
| ResponseMetadata.Action | string | getBalance |
| Result.balance | float | 当前账户余额（元） |
| Result.status | string | 账户状态标识 |
| Result.status_label | string | 账户状态中文描述 |
| Result.consumption | object | 消费统计 |
| Result.consumption.total_consumed | float | 累计消费金额（元） |
| Result.consumption.total_recharged | float | 累计充值金额（元） |
| Result.consumption.total_refunded | float | 累计退款金额（元） |
| Result.consumption.transaction_count | integer | 交易总笔数 |
| Result.currency | string | 货币单位，固定为 CNY |
响应示例：
{
"ResponseMetadata": {
"Action": "getBalance"
},
"Result": {
"balance": 150.00,
"status": "active",
"status_label": "正常",
"consumption": {
"total_consumed": 350.00,
"total_recharged": 500.00,
"total_refunded": 0.00,
"transaction_count": 42
},
"currency": "CNY"
}
}
错误码¶
| 错误码 | HTTP 状态码 | 说明 |
|---|---|---|
| InternalError | 500 | 服务器内部错误 |
用途
可用于在调用 StartVoiceChat 前主动检查余额，避免因余额不足导致请求失败。
使用注意事项¶
RoomId 管理¶
- RoomId 在同一账号下唯一
- getScenes、StartVoiceChat、StopVoiceChat 中的 RoomId 必须一致
- 系统会自动管理 RoomId 的内部映射，无需关注实现细节
计费说明¶
- 计费按对话时长计算，单位为小时
- 费用 = 对话时长 × AI 导师场景单价
- 费用在 StopVoiceChat 时自动扣除
- 计费信息通过响应中的 BillingInfo 返回
房间复用¶
- 同一 RoomId 重复调用 StartVoiceChat 会先结算上次会话费用
- 结算后自动开始新的会话
超时保护机制¶
为防止客户忘记调用 StopVoiceChat 造成不必要的费用损失，系统提供多层保护策略：
1. 客户端控制策略（推荐）
推荐做法
建议在客户端实现用户语音活动检测，当用户一段时间未说话时自动结束对话。这样可以：
- 确保客户端状态与服务端同步
- 提供更好的用户体验
- 避免"客户端显示连接中，但 AI 导师已退出"的尴尬情况
具体实现方式：
| 策略 | 说明 |
|---|---|
| 语音活动检测 | 检测用户是否正在说话 |
| 倒计时机制 | 用户停止说话后开始倒计时（如 30 秒） |
| 自动关闭 | 倒计时结束后调用 StopVoiceChat |
| 用户提示 | 倒计时期间提示用户即将结束对话 |
完整的客户端实现代码请参考 前端示例项目。
2. 服务端状态监控（快速接入方案）
如果希望快速接入，可以启用服务端状态监控，将超时检测托管给服务器：
| 项目 | 说明 |
|---|---|
| 启用方式 | StartVoiceChat 时设置 EnableStatusMonitor: true |
| 超时阈值 | 5 分钟 |
| 触发条件 | AI 导师状态超过 5 分钟未更新 |
| 自动操作 | 系统自动结束对话并执行计费 |
注意事项
启用服务端状态监控可以减少不必要的费用损失，但可能出现客户端显示"连接中"而 AI 导师已退出房间的情况。如果对用户体验要求较高，建议采用客户端控制策略。
3. 房间超时保护（默认启用）
作为最终的兜底措施，服务端默认启用房间超时保护：
| 项目 | 说明 |
|---|---|
| 启用方式 | 默认启用，无需配置 |
| 超时阈值 | 2 小时 |
| 触发条件 | 对话持续超过 2 小时未主动关闭 |
| 自动操作 | 系统自动结束对话并执行计费 |