{
"success": true,
"message": "",
"data": {}
}
失败响应：
{
"success": false,
"message": "错误信息"
}
说明：
HTTP 200success 判断是否成功message 定位原因| 字段 | 值 | 含义 |
|---|---|---|
| 用户/映射状态 | 1 | 启用 |
| 用户/映射状态 | 2 | 禁用 |
| Token 状态 | 1 | 启用 |
| Token 状态 | 2 | 禁用 |
| Token 状态 | 3 | 已过期 |
| Token 状态 | 4 | 已耗尽 |
type | 含义 |
|---|---|
0 | 全部 |
1 | 充值 |
2 | 消耗 |
3 | 管理操作 |
4 | 系统日志 |
5 | 错误日志 |
6 | 退款 |
User.Quota）quota_used 表示项目累计消耗user_quota_remaining 表示所属用户当前真实余额quota_limited_by 当前固定返回 user额度换算规则：
1 USD = 500000 quota
quota = 美元金额 x 500000
美元金额 = quota / 500000
充值、退款、重置、调账接口中真正影响余额的字段分别是：
quotarefund_quotatarget_quotadelta_quotaamount、refund_amount、currency、metadata 等字段仅用于审计与对账，不参与自动换算。
| 场景 | 幂等键 |
|---|---|
| 用户创建/获取 | external_user_id（可选但推荐） |
| 项目创建/获取 | external_project_id（可选但推荐） |
| 用户充值 | external_order_id（必填） |
| 充值退款/冲正 | external_refund_id（必填） |
| 余额重置 | external_reset_id（必填） |
| 余额调账 | external_adjust_id（必填） |
平台侧建议始终持久化并传入上述外部 ID，避免重复开户、重复项目创建和重复资金变更。
platform_user_id 后按需充值/退款/调账token_key 调用 /v1/chat/completions 等模型接口| 方法 | 路径 | 说明 |
|---|---|---|
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 明细 |
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"
}
}
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": "套餐充值"
}
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": "部分退款"
}
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
}
项目创建成功后，使用响应中的 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": "你好"}
]
}'
platform_user_id / platform_project_id？external_* 字段用于接入侧幂等与映射，系统内部查询主键是平台 ID，因此查询接口统一采用平台 ID。
external_user_id 或 external_project_id 会怎样？每次 upsert 都会被视为新建，可能造成重复用户或重复项目。
metadata 为什么经常返回字符串？部分场景会序列化存储，返回时可能是 JSON 字符串。调用方应做好字符串与对象两种格式兼容。
不能。用户禁用会阻断其名下项目 Token 的模型调用权限。
x-request-id、external_* 幂等键和业务订单号success=false 和额度不足场景建立告警