Loading layout…
平台开放接口(Platform Open API) | Let AI Run平台开放接口(Platform Open API)
本文档用于第三方平台服务端接入。所有接口均通过平台级 Key 鉴权,默认基础路径为 /api/platform/open。
1. 基础信息
- 文档版本:
V1(含部分 V2 字段)
- 适用对象:第三方平台服务端
- 鉴权方式:
Authorization: Bearer <platform-key>
- 响应判定:请始终以响应体中的
success 字段作为成功依据
2. 业务模型
- 一个第三方平台对应一个平台级 Key
- 一个平台下可创建多个平台用户(
platform_user_id)
- 一个平台用户可创建多个项目(
platform_project_id)
- 每个项目对应一个独立
token_key,用于模型调用
- 平台 Key 仅用于管理类接口,不用于模型推理接口
3. 通用响应格式
成功响应:
{
"success": true,
"message": "",
"data": {}
}
{
"success": false,
"message": "错误信息"
}
- 成功与失败通常都返回
HTTP 200
- 必须基于
success 判断是否成功
- 失败时读取
message 定位原因
4. 状态与字段语义
4.1 状态值
| 字段 | 值 | 含义 |
|---|
| 用户/映射状态 | 1 | 启用 |
| 用户/映射状态 | 2 | 禁用 |
| Token 状态 | 1 | 启用 |
| Token 状态 | 2 | 禁用 |
| Token 状态 | 3 | 已过期 |
| Token 状态 | 4 | 已耗尽 |
4.2 日志类型
type | 含义 |
|---|
0 | 全部 |
1 | 充值 |
2 | 消耗 |
3 | 管理操作 |
4 | 系统日志 |
5 | 错误日志 |
6 | 退款 |
4.3 额度语义
- 真实额度来源是用户维度余额(
User.Quota)
- 项目维度
quota_used 表示项目累计消耗
- 项目维度
user_quota_remaining 表示所属用户当前真实余额
quota_limited_by 当前固定返回 user
1 USD = 500000 quota
quota = 美元金额 x 500000
美元金额 = quota / 500000
充值、退款、重置、调账接口中真正影响余额的字段分别是:
- 充值:
quota
- 退款/冲正:
refund_quota
- 余额重置:
target_quota
- 余额调账:
delta_quota
amount、refund_amount、currency、metadata 等字段仅用于审计与对账,不参与自动换算。
5. 幂等规则
| 场景 | 幂等键 |
|---|
| 用户创建/获取 | external_user_id(可选但推荐) |
| 项目创建/获取 | external_project_id(可选但推荐) |
| 用户充值 | external_order_id(必填) |
| 充值退款/冲正 | external_refund_id(必填) |
| 余额重置 | external_reset_id(必填) |
| 余额调账 | external_adjust_id(必填) |
平台侧建议始终持久化并传入上述外部 ID,避免重复开户、重复项目创建和重复资金变更。
6. 推荐接入流程
- 在后台创建并保存平台 Key
- 调用“创建或获取平台用户”
- 拿到
platform_user_id 后按需充值/退款/调账
- 调用“创建或获取项目并返回 Token”
- 使用项目
token_key 调用 /v1/chat/completions 等模型接口
- 使用查询接口回收用户、项目、充值与消耗数据
7. 接口列表
| 方法 | 路径 | 说明 |
|---|
POST | /api/platform/open/users/upsert | 创建或获取平台用户 |
POST | /api/platform/open/users/:platform_user_id/disable | 禁用平台用户 |
POST | /api/platform/open/users/:platform_user_id/enable | 启用平台用户 |
GET | /api/platform/open/users/:platform_user_id/summary | 查询用户额度概览 |
GET | /api/platform/open/users/:platform_user_id/logs | 查询用户消耗明细 |
POST | /api/platform/open/users/:platform_user_id/topups | 给用户充值额度 |
POST | /api/platform/open/users/:platform_user_id/topups/refund | 充值退款或冲正 |
POST | /api/platform/open/users/:platform_user_id/balance/reset | 重置用户剩余额度 |
POST | /api/platform/open/users/:platform_user_id/balance/adjust | 用户余额增减调账 |
GET | /api/platform/open/users/:platform_user_id/topups | 查询用户充值记录 |
POST | /api/platform/open/users/:platform_user_id/projects/upsert | 创建或获取项目并返回 Token |
POST | /api/platform/open/projects/:platform_project_id/disable | 禁用项目 |
POST | /api/platform/open/projects/:platform_project_id/enable | 启用项目 |
GET | /api/platform/open/projects/:platform_project_id/summary | 查询项目 Token 汇总 |
GET | /api/platform/open/projects/:platform_project_id/logs | 查询项目 Token 明细 |
8. 核心接口示例
8.1 创建或获取平台用户
POST /api/platform/open/users/upsert
Authorization: Bearer <platform-key>
Content-Type: application/json
{
"external_user_id": "u_10001",
"name": "Alice",
"email": "alice@example.com",
"phone": "+86-13800000000",
"metadata": {
"channel": "partner-a"
}
}
8.2 给平台用户充值额度
POST /api/platform/open/users/:platform_user_id/topups
Authorization: Bearer <platform-key>
Content-Type: application/json
{
"external_order_id": "ord_20260518_0001",
"quota": 5000000,
"amount": "72.00",
"currency": "CNY",
"remark": "套餐充值"
}
8.3 平台充值退款或冲正
POST /api/platform/open/users/:platform_user_id/topups/refund
Authorization: Bearer <platform-key>
Content-Type: application/json
{
"external_refund_id": "refund_20260518_0001",
"external_order_id": "ord_20260518_0001",
"refund_quota": 1000000,
"refund_amount": "14.40",
"currency": "CNY",
"remark": "部分退款"
}
8.4 创建或获取项目并返回 Token
POST /api/platform/open/users/:platform_user_id/projects/upsert
Authorization: Bearer <platform-key>
Content-Type: application/json
{
"external_project_id": "p_10001",
"name": "客服机器人",
"expired_time": 1798761599,
"remain_quota": 0
}
9. 项目 Token 调用模型接口
项目创建成功后,使用响应中的 token_key 调用模型接口,而不是平台 Key:
curl --request POST \
--url https://api.letai.run/v1/chat/completions \
--header 'Authorization: Bearer <token_key>' \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-5.4",
"messages": [
{"role": "user", "content": "你好"}
]
}'
10. 常见问题
为什么查询接口主要使用 platform_user_id / platform_project_id?
external_* 字段用于接入侧幂等与映射,系统内部查询主键是平台 ID,因此查询接口统一采用平台 ID。
如果不传 external_user_id 或 external_project_id 会怎样?
每次 upsert 都会被视为新建,可能造成重复用户或重复项目。
metadata 为什么经常返回字符串?
部分场景会序列化存储,返回时可能是 JSON 字符串。调用方应做好字符串与对象两种格式兼容。
用户禁用后,项目 Token 还能调用吗?
不能。用户禁用会阻断其名下项目 Token 的模型调用权限。
11. 对接建议
- 平台 Key 与项目 Token 分离存储,分别最小权限使用
- 全链路记录
x-request-id、external_* 幂等键和业务订单号
- 充值/退款/调账接口必须做调用侧重试与去重
- 对
success=false 和额度不足场景建立告警